Merge pull request #647 from epage/docs

docs: Clean up

README.md

@@ -28,11 +28,6 @@ values back to the configuration file(s)!
 
 ## Usage
 
-```toml
-[dependencies]
-config = "0.14.0"
-```
-
 ### Feature flags
 
  - `ini` - Adds support for reading INI files

src/builder.rs

@@ -125,9 +125,8 @@ enum SourceType {
 impl BuilderState for DefaultState {}
 impl BuilderState for AsyncState {}
 
+/// Operations allowed in any state
 impl<St: BuilderState> ConfigBuilder<St> {
-    // operations allowed in any state
-
     /// Set a default `value` at `key`
     ///
     /// This value can be overwritten by any [`Source`], [`AsyncSource`] or override.
@@ -183,9 +182,8 @@ impl<St: BuilderState> ConfigBuilder<St> {
     }
 }
 
+/// Operations allowed in sync state
 impl ConfigBuilder<DefaultState> {
-    // operations allowed in sync state
-
     /// Registers new [`Source`] in this builder.
     ///
     /// Calling this method does not invoke any I/O. [`Source`] is only saved in internal register for later use.
@@ -273,9 +271,8 @@ impl ConfigBuilder<DefaultState> {
     }
 }
 
+/// Operations allowed in async state
 impl ConfigBuilder<AsyncState> {
-    // operations allowed in async state
-
     /// Registers new [`Source`] in this builder.
     ///
     /// Calling this method does not invoke any I/O. [`Source`] is only saved in internal register for later use.

src/config.rs

@@ -11,8 +11,9 @@ use crate::ser::ConfigSerializer;
 use crate::source::Source;
 use crate::value::{Table, Value};
 
-/// A prioritized configuration repository. It maintains a set of
-/// configuration sources, fetches values to populate those, and provides
+/// A prioritized configuration repository.
+///
+/// It maintains a set of configuration sources, fetches values to populate those, and provides
 /// them according to the source's priority.
 #[derive(Clone, Debug)]
 pub struct Config {

src/file/mod.rs

@@ -15,6 +15,14 @@ pub use self::format::FileFormat;
 pub use self::source::file::FileSourceFile;
 pub use self::source::string::FileSourceString;
 
+/// An extension of [`Format`] trait.
+///
+/// Associates format with file extensions, therefore linking storage-agnostic notion of format to a file system.
+pub trait FileStoredFormat: Format {
+    /// Returns a vector of file extensions, for instance `[yml, yaml]`.
+    fn file_extensions(&self) -> &'static [&'static str];
+}
+
 /// A configuration source backed up by a file.
 ///
 /// It supports optional automatic file format discovery.
@@ -30,14 +38,6 @@ pub struct File<T, F> {
     required: bool,
 }
 
-/// An extension of [`Format`] trait.
-///
-/// Associates format with file extensions, therefore linking storage-agnostic notion of format to a file system.
-pub trait FileStoredFormat: Format {
-    /// Returns a vector of file extensions, for instance `[yml, yaml]`.
-    fn file_extensions(&self) -> &'static [&'static str];
-}
-
 impl<F> File<FileSourceString, F>
 where
     F: FileStoredFormat + 'static,
@@ -67,15 +67,32 @@ where
 impl File<FileSourceFile, FileFormat> {
     /// Given the basename of a file, will attempt to locate a file by setting its
     /// extension to a registered format.
-    pub fn with_name(name: &str) -> Self {
+    pub fn with_name(base_name: &str) -> Self {
         Self {
             format: None,
             required: true,
-            source: FileSourceFile::new(name.into()),
+            source: FileSourceFile::new(base_name.into()),
         }
     }
 }
 
+impl<T, F> File<T, F>
+where
+    F: FileStoredFormat + 'static,
+    T: FileSource<F>,
+{
+    pub fn format(mut self, format: F) -> Self {
+        self.format = Some(format);
+        self
+    }
+
+    /// Set required to false to make a file optional when building the config.
+    pub fn required(mut self, required: bool) -> Self {
+        self.required = required;
+        self
+    }
+}
+
 impl<'a> From<&'a Path> for File<FileSourceFile, FileFormat> {
     fn from(path: &'a Path) -> Self {
         Self {
@@ -96,23 +113,6 @@ impl From<PathBuf> for File<FileSourceFile, FileFormat> {
     }
 }
 
-impl<T, F> File<T, F>
-where
-    F: FileStoredFormat + 'static,
-    T: FileSource<F>,
-{
-    pub fn format(mut self, format: F) -> Self {
-        self.format = Some(format);
-        self
-    }
-
-    /// Set required to false to make a file optional when building the config.
-    pub fn required(mut self, required: bool) -> Self {
-        self.required = required;
-        self
-    }
-}
-
 impl<T, F> Source for File<T, F>
 where
     F: FileStoredFormat + Debug + Clone + Send + Sync + 'static,

src/file/source/mod.rs

@@ -6,7 +6,7 @@ use std::fmt::Debug;
 
 use crate::{file::FileStoredFormat, Format};
 
-/// Describes where the file is sourced
+/// Describes where the [`File`][super::File] is sourced
 pub trait FileSource<T>: Debug + Clone
 where
     T: Format + FileStoredFormat,

src/lib.rs

@@ -1,21 +1,29 @@
-//! Config organizes hierarchical or layered configurations for Rust applications.
+//! [`Config`] organizes hierarchical or layered configurations for Rust applications.
 //!
-//! Config lets you set a set of default parameters and then extend them via merging in
+//! [`Config`] lets you set a set of [default parameters][ConfigBuilder::set_default] and then extend them via merging in
 //! configuration from a variety of sources:
 //!
-//!  - Environment variables
-//!  - String literals in well-known formats
-//!  - Another Config instance
-//!  - 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)
+//!  - [Environment variables][Environment]
+//!  - [String literals][FileSourceString] in [well-known formats][FileFormat]
+//!  - Another [`Config`] instance
+//!  - [Files][FileSourceFile] in [well known formats][FileFormat] and custom ones defined with [`Format`] trait
+//!  - Manual, programmatic [overrides][ConfigBuilder::set_override]
 //!
-//! Additionally, Config supports:
+//! Additionally, [`Config`] supports:
 //!
 //!  - Live watching and re-reading of configuration files
 //!  - Deep access into the merged configuration via a path syntax
 //!  - Deserialization via `serde` of the configuration or any subset defined via a path
 //!
-//! See the [examples](https://github.com/mehcode/config-rs/tree/master/examples) for
+//! # Example
+//!
+//! ```rust
+//! # #[cfg(feature = "toml")] {
+#![doc = include_str!("../examples/simple/main.rs")]
+//! # }
+//! ```
+//!
+//! See more [examples](https://github.com/mehcode/config-rs/tree/master/examples) for
 //! general usage information.
 
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]

src/map.rs

@@ -1,4 +1,7 @@
+/// The backing store for [`Config`][crate::Config]
+pub type Map<K, V> = InternalMap<K, V>;
+
 #[cfg(not(feature = "preserve_order"))]
-pub type Map<K, V> = std::collections::HashMap<K, V>;
+type InternalMap<K, V> = std::collections::HashMap<K, V>;
 #[cfg(feature = "preserve_order")]
-pub type Map<K, V> = indexmap::IndexMap<K, V>;
+type InternalMap<K, V> = indexmap::IndexMap<K, V>;

src/source.rs

@@ -13,8 +13,8 @@ use crate::value::{Value, ValueKind};
 pub trait Source: Debug {
     fn clone_into_box(&self) -> Box<dyn Source + Send + Sync>;
 
-    /// Collect all configuration properties available from this source and return
-    /// a Map.
+    /// Collect all configuration properties available from this source into
+    /// a [`Map`].
     fn collect(&self) -> Result<Map<String, Value>>;
 
     /// Collects all configuration properties to a provided cache.

src/value.rs

@@ -9,8 +9,8 @@ use crate::map::Map;
 
 /// Underlying kind of the configuration value.
 ///
-/// Standard operations on a `Value` by users of this crate do not require
-/// knowledge of `ValueKind`. Introspection of underlying kind is only required
+/// Standard operations on a [`Value`] by users of this crate do not require
+/// knowledge of [`ValueKind`]. Introspection of underlying kind is only required
 /// when the configuration values are unstructured or do not have known types.
 #[derive(Debug, Clone, PartialEq)]
 pub enum ValueKind {