Add documentation to file related types

5 files changed, 32 insertions, 3 deletions

diff --git a/src/file/extension.rs b/src/file/extension.rs
index bb247c8..75ca557 100644
--- a/src/file/extension.rs
+++ b/src/file/extension.rs
@@ -1,3 +1,14 @@
+/// Describes an entity that can return file extensions.
+///
+/// Meant primarily for [`Format`](crate::Format) trait.
+/// Since [`Format`](crate::Format) only describes certain internal encoding, for instance JSON or Yaml
+/// it is not necessarily bound to file extension name.
+///
+///In networking context JSONs are used without file extensions.
+/// One can also imagine some encodings that do not necessarily have file extension associated, for instance
+/// MessagePack or bincode.
+/// Hence the decision to have extensions separated from [`Format`](crate::Format).
 pub trait FileExtensions {
+    /// Returns a vector of file extensions, for instance `[yml, yaml]`.
     fn extensions(&self) -> &Vec<&'static str>;
 }
diff --git a/src/file/format/mod.rs b/src/file/format/mod.rs
index d1a9a71..4238227 100644
--- a/src/file/format/mod.rs
+++ b/src/file/format/mod.rs
@@ -26,6 +26,9 @@ mod ron;
 #[cfg(feature = "json5")]
 mod json5;
 
+/// File formats provided by the library.
+///
+/// Although it is possible to define custom formats using [`Format`] trait it is recommended to use FileFormat if possible.
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
 pub enum FileFormat {
     /// TOML (parsed with toml)
diff --git a/src/file/mod.rs b/src/file/mod.rs
index 6c1e4c5..fa6d383 100644
--- a/src/file/mod.rs
+++ b/src/file/mod.rs
@@ -18,6 +18,9 @@ pub use self::extension::FileExtensions;
 pub use self::source::file::FileSourceFile;
 pub use self::source::string::FileSourceString;
 
+/// A configuration source backed up by a file.
+///
+/// It supports optional automatic file format discovery.
 #[derive(Clone, Debug)]
 pub struct File<T, F>
 where
diff --git a/src/format.rs b/src/format.rs
index c32dbae..279b4ab 100644
--- a/src/format.rs
+++ b/src/format.rs
@@ -3,7 +3,19 @@ use std::{collections::HashMap, error::Error};
 use crate::value::Value;
 use crate::map::Map;
 
+/// Describes a format of configuration source data
+///
+/// Implementations of this trait can be used to convert [`File`](crate::File) sources to configuration data.
+///
+/// There can be various formats, some of them provided by this library, such as JSON, Yaml and other.
+/// This trait enables users of the library to easily define their own, even proprietary formats without
+/// the need to alter library sources.
+///
+/// What is more, it is recommended to use this trait with custom [`Source`](crate::Source)s and their async counterparts.
 pub trait Format {
+    /// Parses provided content into configuration values understood by the library.
+    ///
+    /// It also allows specifying optional URI of the source associated with format instance that can facilitate debugging.
     fn parse(
         &self,
         uri: Option<&String>,
diff --git a/src/lib.rs b/src/lib.rs
index 73abfe3..e5ee901 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,9 +4,9 @@
 //! configuration from a variety of sources:
 //!
 //!  - Environment variables
+//!  - String literals in well-known formats
 //!  - Another Config instance
-//!  - Remote configuration: etcd, Consul
-//!  - Files: TOML, JSON, YAML, INI, RON, JSON5
+//!  - Files: TOML, JSON, YAML, INI, RON, JSON5 and custom ones defined with Format trait
 //!  - Manual, programmatic override (via a `.set` method on the Config instance)
 //!
 //! Additionally, Config supports:
@@ -68,8 +68,8 @@ pub use crate::builder::ConfigBuilder;
 pub use crate::config::Config;
 pub use crate::env::Environment;
 pub use crate::error::ConfigError;
-pub use crate::file::{File, FileFormat, FileSourceFile, FileSourceString};
 pub use crate::map::Map;
+pub use crate::file::{File, FileExtensions, FileFormat, FileSourceFile, FileSourceString};
 pub use crate::format::Format;
 pub use crate::source::AsyncSource;
 pub use crate::source::Source;