Merge pull request #8 from utkarshgupta137/master

Docs/readme: minor changes & bump Cargo version

Cargo.toml

@@ -4,12 +4,12 @@ description = "An unopinionated library for obtaining configuration, data, cache
 documentation = "https://docs.rs/etcetera"
 edition = "2018"
 homepage = "https://github.com/lunacookies/etcetera"
-keywords = ["xdg", "dirs", "directories", "directory", "basedir", "app_dirs", "cli_dirs", "config", "path", "folder"]
+keywords = ["xdg", "dirs", "directories", "basedir", "path", "folder", "directory", "app_dirs", "cli_dirs", "config"]
 license = "MIT OR Apache-2.0"
 name = "etcetera"
 readme = "README.md"
 repository = "https://github.com/lunacookies/etcetera"
-version = "0.5.0"
+version = "0.6.0"
 
 [dependencies]
 cfg-if = "1.0.0"

README.md

@@ -5,14 +5,18 @@
 
 # Etcetera
 
-This is a Rust library that allows you to determine the locations of configuration, data, cache & other files for your application. Existing Rust libraries generally do not give you a choice in terms of which standards/conventions (Etcetera calls these ‘strategies’) they follow. Etcetera, on the other hand, gives you the choice.
+This is a Rust library that allows you to determine the locations of configuration, data, cache & other files for your application.
+Existing Rust libraries generally do not give you a choice in terms of which standards/conventions they follow.
+Etcetera, on the other hand, gives you the choice.
 
-Etcetera supports the following strategies:
+## Conventions
+Etcetera supports the following conventions:
 - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html)
-- the [Known Folder Locations](https://msdn.microsoft.com/en-us/library/windows/desktop/dd378457.aspx)
-- the [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html)
-- the "Unix Single-folder Strategy" i.e. everything in `~/.myapp`
+- Apple's [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html)
+- Window's [Known Folder Locations](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid)
+- the "Unix Single-folder Convention" i.e. everything in `~/.myapp`
 
+## Strategies
 Etcetera has 2 modes of operation: `BaseStrategy` & `AppStrategy`:
 - With `BaseStrategy`, you just get the location of the respective directory. For eg. for `config_dir()`:
   - XDG: `~/.config`
@@ -27,10 +31,12 @@ Etcetera has 2 modes of operation: `BaseStrategy` & `AppStrategy`:
 
 Note: the location of the home (~) is determined by the [`home`](https://docs.rs/home/0.5.4/home/fn.home_dir.html) crate.
 
+### Convenience functions
 Etcetera also provides convenience functions for selecting the appropriate strategy on each platform:
 - `base_strategy::choose_base_strategy` & `app_strategy::choose_app_strategy`: Uses `Windows` on Windows & `XDG` everywhere else.
   This is used by most CLI tools & some GUI tools on each platform.
 - `base_strategy::choose_native_strategy` & `app_strategy::choose_native_strategy`: Uses `Windows` on Windows, `Apple` on macOS/iOS, & `XDG` everywhere else.
   This is used by most GUI applications on each platform.
 
-See the documentation for examples.
+##
+See the ![documentation](https://docs.rs/etcetera) for examples.

src/app_strategy.rs

@@ -69,7 +69,7 @@ macro_rules! in_dir_method {
     }};
 }
 
-/// Allows applications to retrieve the paths of configuration, data and cache directories specifically for them.
+/// Allows applications to retrieve the paths of configuration, data, and cache directories specifically for them.
 pub trait AppStrategy: Sized {
     /// The error type returned by `new`.
     type CreationError: std::error::Error;
@@ -87,11 +87,11 @@ pub trait AppStrategy: Sized {
     fn cache_dir(&self) -> PathBuf;
 
     /// Gets the state directory for your application.
-    /// State directory may not to exist for all platforms.
+    /// State directory may not to exist for all conventions.
     fn state_dir(&self) -> Option<PathBuf>;
 
     /// Gets the runtime directory for your application.
-    /// Runtime directory may not to exist for all platforms.
+    /// Runtime directory may not to exist for all conventions.
     fn runtime_dir(&self) -> Option<PathBuf>;
 
     /// Constructs a path inside your application’s configuration directory to which a path of your choice has been appended.

src/app_strategy/windows.rs

@@ -2,7 +2,7 @@ use crate::base_strategy;
 use crate::base_strategy::BaseStrategy;
 use std::path::PathBuf;
 
-/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern.
+/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
 ///
 /// ```
 /// use etcetera::app_strategy::AppStrategy;

src/base_strategy.rs

@@ -1,8 +1,8 @@
-//! These strategies simply provide the user’s configuration, data and cache directories, without knowing about the application specifically.
+//! These strategies simply provide the user’s configuration, data, and cache directories, without knowing about the application specifically.
 
 use std::path::PathBuf;
 
-/// Provides configuration, data and cache directories of the current user.
+/// Provides configuration, data, and cache directories of the current user.
 pub trait BaseStrategy: Sized {
     /// The error type returned by `new`.
     type CreationError: std::error::Error;
@@ -20,11 +20,11 @@ pub trait BaseStrategy: Sized {
     fn cache_dir(&self) -> PathBuf;
 
     /// Gets the user’s state directory.
-    /// State directory may not exist for all platforms.
+    /// State directory may not exist for all conventions.
     fn state_dir(&self) -> Option<PathBuf>;
 
     /// Gets the user’s runtime directory.
-    /// Runtime directory may not exist for all platforms.
+    /// Runtime directory may not exist for all conventions.
     fn runtime_dir(&self) -> Option<PathBuf>;
 }
 

src/base_strategy/windows.rs

@@ -1,6 +1,6 @@
 use std::path::PathBuf;
 
-/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern.
+/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
 ///
 /// ```
 /// use etcetera::base_strategy::BaseStrategy;

src/base_strategy/xdg.rs

@@ -3,13 +3,14 @@ use std::path::PathBuf;
 
 /// This strategy implements the [XDG Base Directories Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It is the most common on Linux, but is increasingly being adopted elsewhere.
 ///
-/// In this first example the relevant XDG environment variables have been unset so as to demonstrate the strategy’s behaviour when it has to fall back to the defaults.
+/// This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories.
 ///
 /// ```
 /// use etcetera::base_strategy::BaseStrategy;
 /// use etcetera::base_strategy::Xdg;
 /// use std::path::Path;
 ///
+/// // Remove the environment variables that the strategy reads from.
 /// std::env::remove_var("XDG_CONFIG_HOME");
 /// std::env::remove_var("XDG_DATA_HOME");
 /// std::env::remove_var("XDG_CACHE_HOME");
@@ -42,7 +43,7 @@ use std::path::PathBuf;
 /// );
 /// ```
 ///
-/// And here is another example with the environment variables set to demonstrate that the strategy really does read them:
+/// This next example gives the environment variables values:
 ///
 /// ```
 /// use etcetera::base_strategy::BaseStrategy;
@@ -106,17 +107,14 @@ use std::path::PathBuf;
 /// );
 /// ```
 ///
-/// The specification states that:
-///
-/// > All paths set in these environment variables must be absolute. If an implementation encounters a relative path in any of these variables it should consider the path invalid and ignore it.
-///
-/// In this example the environment variables have been given relative values. The strategy behaves correctly and uses the defaults:
+/// The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour:
 ///
 /// ```
 /// use etcetera::base_strategy::BaseStrategy;
 /// use etcetera::base_strategy::Xdg;
 /// use std::path::Path;
 ///
+/// // Remove the environment variables that the strategy reads from.
 /// std::env::set_var("XDG_CONFIG_HOME", "foo/");
 /// std::env::set_var("XDG_DATA_HOME", "bar/");
 /// std::env::set_var("XDG_CACHE_HOME", "baz/");
@@ -127,6 +125,7 @@ use std::path::PathBuf;
 ///
 /// let home_dir = etcetera::home_dir().unwrap();
 ///
+/// // We still get the default values.
 /// assert_eq!(
 ///     base_strategy.config_dir().strip_prefix(&home_dir),
 ///     Ok(Path::new(".config/"))

src/lib.rs

@@ -1,10 +1,19 @@
-//! This is a Rust library that allows you to determine the locations of configuration, data, cache & other files for your application. Existing Rust libraries generally do not give you a choice in terms of which standards/conventions (Etcetera calls these ‘strategies’) they follow. Etcetera, on the other hand, gives you the choice.
+//! This is a Rust library that allows you to determine the locations of configuration, data, cache & other files for your application.
+//! Existing Rust libraries generally do not give you a choice in terms of which standards/conventions they follow.
+//! Etcetera, on the other hand, gives you the choice.
+//!
+//! # Conventions
+//! Etcetera supports the following conventions:
+//! - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html)
+//! - Apple's [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html)
+//! - Window's [Known Folder Locations](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid)
+//! - the "Unix Single-folder Convention" i.e. everything in `~/.myapp`
 //!
 //! # Strategies
-//! If you want to get started quickly, you can use the provided convenience functions that use the default strategies (as determined arbitrarily by yours truly) or the native strategies for each OS.
+//! If you want to get started quickly, you can use the following convenience functions that use the default strategies (as determined arbitrarily by yours truly) or the native strategies for each OS.
 //!
 //! ## BaseStrategy
-//! This first example is for when you just want the path to a configuration, data or cache directory (this is called a ‘base strategy’):
+//! If you just want to get the path to a configuration, data, cache or another directory, you can use the `choose_base_strategy` function.
 //!
 //! ```
 //! use etcetera::base_strategy;
@@ -20,16 +29,14 @@
 //! ```
 //!
 //! ## AppStrategy
-//! Here is an example where you provide Etcetera with some basic information about your application, and Etcetera will in turn give you a path that includes this information (this is called an ‘app strategy’).
+//! If you want to get the path to a configuration, data, cache or another directory, and you want to follow the naming conventions for your application, you can use the `choose_app_strategy` function.
 //!
-//! Let’s take an application created by Acme Corp with the name Frobnicator Plus and the top-level domain of `.org` as an example.
+//! Let’s take an application created by `Acme Corp` with the name `Frobnicator Plus` and the top-level domain of `jrg` as an example.
 //! - XDG strategy would place these in `~/.config/frobnicator-plus`.
 //! - Unix strategy would place these in `~/.frobnicator-plus`.
 //! - Apple strategy would place these in `~/Library/Preferences/org.acmecorp.FrobnicatorPlus`.
 //! - Windows strategy would place these in `~\AppData\Roaming\Acme Corp\Frobnicator Plus`.
 //!
-//! Etcetera takes care of the distinctions.
-//!
 //! ```
 //! use etcetera::app_strategy;
 //! use etcetera::app_strategy::AppStrategy;
@@ -54,11 +61,11 @@
 //! This is used by most CLI tools & some GUI tools on each platform.
 //!
 //! If you're developing a GUI application, you might want to use the "Standard directories" on macOS by using `choose_native_strategy()` instead.
-//! Note that if your application expects the user to modify the configuration files, you still should prefer the `XDG` strategy on macOS.
+//! Note that if your application expects the user to modify the configuration files, you should still prefer the `XDG` strategy on macOS.
 //!
-//! ## Custom Strategies
+//! ## Custom Conventions
 //!
-//! You aren’t limited to the built-in strategies, however – you can implement the relevant traits yourself. Please consider contributing these back, as the more preset strategies there are, the better.
+//! You aren’t limited to the built-in conventions – you can implement the relevant traits yourself. Please consider contributing these back, as the more preset conventions there are, the better.
 //!
 //! # More Examples
 //! Say you were a hardened Unix veteran, and didn’t want to have any of this XDG nonsense, clutter in the home directory be damned! Instead of using `choose_app_strategy` or `choose_base_strategy`, you can pick a strategy yourself. Here’s an example using the [`Unix`](app_strategy/struct.Unix.html) strategy – see its documentation to see what kind of folder structures it produces: