Commit: 75aeabe2d9b70e454de027da0ad404a2697c748b - mlib (git)

A D package containing my single-file modules

Commit MetaInfo

• Revision: 75aeabe2d9b70e454de027da0ad404a2697c748b (tree)
• Time: 2023-03-25 21:24:57
• Author: nemophila <stigma+osdn@disr...>
• Commiter: nemophila

Log Message

directories: Documentation for ProjectDirectories

Change Summary

• modified: source/mlib/directories.d

Incremental Difference

--- a/source/mlib/directories.d
+++ b/source/mlib/directories.d
@@ -205,6 +205,13 @@ struct BaseDirectories
 }
 
 ///
+/// Returns a new instance of `BaseDirectories`.
+///
+/// The instance is an immutable snapshop of the state of the system at
+/// the time this function is called.  Subsequent changes to the state
+/// of the system are not reflected in instances created prior to such
+/// a change.
+///
 nothrow BaseDirectories getBaseDirectories()
 {
     // OS X first so it doesn't get mixed with Posix.
@@ -253,17 +260,207 @@ unittest
 }
 
 ///
+/// `ProjectDirectories ` computes the location of cache, config, or
+/// data directories for a specific application, which are derived from
+/// the standard directories and the name of the project/organisation.
+///
+/// ## Examples
+///
+/// All examples in this section are computed with a user named *Elq*,
+/// and a `ProjectDirectories` instance created with the following
+/// information:
+///
+/// ```d
+/// ProjectDirectories projectDirs = getProjectDirectories("com", "Foo Corp", "Bar App");
+/// ```
+///
+/// Example of `ProjectDirectories#configDir` value in different
+/// operating systems:
+///
+/// $(UL
+///  $(LI $(B Posix): `/home/elq/.config/barapp`)
+///  $(LI $(B macOS): $(RED Platform not supported))
+///  $(LI $(B Windows): `C:\Users\Elq\AppData\Roaming\Foo Corp\Bar App\config`)
+/// )
+///
 struct ProjectDirectories
 {
+    ///
+    /// The path to the project's cache directory in which
+    /// `<project_path>` is the value of `ProjectDirectories#projectPath`.
+    ///
+    /// $(TABLE
+    ///  $(TR
+    ///   $(TH Platform)
+    ///   $(TH Value)
+    ///   $(TH Example)
+    ///   )
+    ///  $(TR
+    ///   $(TD Posix)
+    ///   $(TD `$XDG_CACHE_HOME/<project_path>` (fallback: `$HOME/.cache/<project_path>`))
+    ///   $(TD /home/elq/.cache/barapp)
+    ///   )
+    ///  $(TR
+    ///   $(TD macOS)
+    ///   $(TD $(RED Platform not supported))
+    ///   $(TD $(RED Platform not supported))
+    ///   )
+    ///  $(TR
+    ///   $(TD Windows)
+    ///   $(TD `FOLDERID_LocalAppData\<project_path>\cache`)
+    ///   $(TD C:\Users\Elq\AppData\Local\Foo Corp\Bar App\cache )
+    ///   )
+    /// )
+    ///
     immutable string cacheDir;
+
+    ///
+    /// The path to the project's configuration directory, in which
+    /// `<project_path>` is the value of `ProjectDirectories#projectPath`.
+    ///
+    /// $(TABLE
+    ///  $(TR
+    ///   $(TH Platform)
+    ///   $(TH Value)
+    ///   $(TH Example)
+    ///   )
+    ///  $(TR
+    ///   $(TD Posix)
+    ///   $(TD `$XDG_CONFIG_HOME/<project_path>` (fallback: `$HOME/.config/<project_path>/`))
+    ///   $(TD /home/elq/.config/barapp)
+    ///   )
+    ///  $(TR
+    ///   $(TD macOS)
+    ///   $(TD $(RED Platform not supported))
+    ///   $(TD $(RED Platform not supported))
+    ///   )
+    ///  $(TR
+    ///   $(TD Windows)
+    ///   $(TD `FOLDERID_RoamingAppData\<project_path>\config`)
+    ///   $(TD C:\Users\Elq\AppData\Roaming\Foo Corp\Bar App\config )
+    ///   )
+    /// )
+    ///
     immutable string configDir;
+
+    ///
+    /// The path to the project's data directory, in which
+    /// `<project_path>` is the value of `ProjectDirectories#projectPath`.
+    ///
+    /// $(TABLE
+    ///  $(TR
+    ///   $(TH Platform)
+    ///   $(TH Value)
+    ///   $(TH Example)
+    ///   )
+    ///  $(TR
+    ///   $(TD Posix)
+    ///   $(TD `$XDG_DATA_HOME/<project_path>` (fallback: `$HOME/.local/share/<project_path>/`))
+    ///   $(TD /home/elq/.local/share/barapp)
+    ///   )
+    ///  $(TR
+    ///   $(TD macOS)
+    ///   $(TD $(RED Platform not supported))
+    ///   $(TD $(RED Platform not supported))
+    ///   )
+    ///  $(TR
+    ///   $(TD Windows)
+    ///   $(TD `FOLDERID_RoamingAppData\<project_path>\data`)
+    ///   $(TD C:\Users\Elq\AppData\Roaming\Foo Corp\Bar App\data )
+    ///   )
+    /// )
+    ///
     immutable string dataDir;
+
+    ///
+    /// The path to the project's local data directory, in which
+    /// `<project_path>` is the value of `ProjectDirectories#projectPath`.
+    ///
+    /// $(TABLE
+    ///  $(TR
+    ///   $(TH Platform)
+    ///   $(TH Value)
+    ///   $(TH Example)
+    ///   )
+    ///  $(TR
+    ///   $(TD Posix)
+    ///   $(TD `$XDG_DATA_HOME/<project_path>` (fallback: `$HOME/.local/share/<project_path>/`))
+    ///   $(TD /home/elq/.local/share/barapp)
+    ///   )
+    ///  $(TR
+    ///   $(TD macOS)
+    ///   $(TD $(RED Platform not supported))
+    ///   $(TD $(RED Platform not supported))
+    ///   )
+    ///  $(TR
+    ///   $(TD Windows)
+    ///   $(TD `FOLDERID_LocalAppData\<project_path>\data`)
+    ///   $(TD C:\Users\Elq\AppData\Local\Foo Corp\Bar App\data )
+    ///   )
+    /// )
+    ///
     immutable string dataLocalDir;
+
+    ///
+    /// The path to the project's preference directory, in which
+    /// `<project_path>` is the value of `ProjectDirectories#projectPath`.
+    ///
+    /// $(TABLE
+    ///  $(TR
+    ///   $(TH Platform)
+    ///   $(TH Value)
+    ///   $(TH Example)
+    ///   )
+    ///  $(TR
+    ///   $(TD Posix)
+    ///   $(TD `$XDG_CONFIG_HOME/<project_path>` (fallback: `$HOME/.config/<project_path>/`))
+    ///   $(TD /home/elq/.config/barapp)
+    ///   )
+    ///  $(TR
+    ///   $(TD macOS)
+    ///   $(TD $(RED Platform not supported))
+    ///   $(TD $(RED Platform not supported))
+    ///   )
+    ///  $(TR
+    ///   $(TD Windows)
+    ///   $(TD `FOLDERID_RoamingAppData\<project_path>\config`)
+    ///   $(TD C:\Users\Elq\AppData\Roaming\Foo Corp\Bar App\config)
+    ///   )
+    /// )
+    ///
     immutable string preferenceDir;
+
+    ///
+    /// The path to the project's data directory, in which
+    /// `<project_path>` is the value of `ProjectDirectories#projectPath`.
+    ///
+    /// $(TABLE
+    ///  $(TR
+    ///   $(TH Platform)
+    ///   $(TH Value)
+    ///   $(TH Example)
+    ///   )
+    ///  $(TR
+    ///   $(TD Posix)
+    ///   $(TD `$XDG_RUNTIME_DIR`)
+    ///   $(TD /run/user/1001/bareapp)
+    ///   )
+    ///  $(TR
+    ///   $(TD macOS)
+    ///   $(TD $(RED Platform not supported))
+    ///   $(TD $(RED Platform not supported))
+    ///   )
+    ///  $(TR
+    ///   $(TD Windows)
+    ///   $(TD $(RED Platform not supported))
+    ///   $(TD $(RED Platform not supported))
+    ///   )
+    /// )
+    ///
     immutable string runtimeDir;
 
     ///
-    /// Returns the project path fragment used to compute the project's
+    /// The project path fragment used to compute the project's
     /// cache/config/data directories.
     ///
     /// The value is derived from the arguments provided to the
@@ -293,6 +490,28 @@ struct ProjectDirectories
 }
 
 ///
+/// Return an instance of `ProjectDirectories` from values describing
+/// the project.
+///
+/// Params:
+///   qualifier =    The reverse domain name notation of the application,
+///                  excluding the organisation or application name itself. $(BR)
+///                  An example string can be passed if no qualifier should
+///                  be used (only affects macOS). $(BR)
+///                  Example values: `"com.example"`, `"org"`, `"co.uk"`, `""`.
+///
+///   organisation = The name of the organisation that develops this application,
+///                  or for which the application is developed.$(BR)
+///                  An empty string can be passed if no organisation should be
+///                  used (only affects macOS and Windows).$(BR)
+///                  Example values: `"Foo Corp"`, `"Alice and Bob Inc"`, `""`.
+///
+///   application =  The name of the application itself.$(BR)
+///                  Example values: `"Bar App"`, `"ExampleProgram"`, `"Unicorn-Programme"`.
+///
+/// Returns: An instance of `ProjectDirectories`, whose directory field values are
+///          based on the `qualifier`, `organisation`, and `application` arguments.
+///
 ProjectDirectories getProjectDirectories(string qualifier, string organisation, string application) nothrow
 in
 {