Add a docs site?

Signed-off-by: Sam Therapy <sam@samtherapy.net>
2024-03-27 15:15:18 +01:00 · 2024-03-27 15:15:18 +01:00 · 4f384523a6
parent e3fa27376c
commit 4f384523a6
21 changed files with 362 additions and 116 deletions
--- a/.config/dotnet-tools.json
+++ b/.config/dotnet-tools.json
@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.75.3",
+      "commands": [
+        "docfx"
+      ]
+    }
+  }
+}
--- a/.github/workflows/documentation.yaml
+++ b/.github/workflows/documentation.yaml
@ -0,0 +1,42 @@
+on:
+  workflow_run:
+    workflows: [Benchmarks]
+    types: [completed]
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+  
+jobs:
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Dotnet Setup
+      uses: actions/setup-dotnet@v3
+      with:
+        dotnet-version: 8.x
+    - run: dotnet tool update -g docfx
+    - name: Build website
+      run: dotnet docfx docs/docfx.json
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_site
+        keep_files: true
+        force_orphan: true
--- a/.gitignore
+++ b/.gitignore
@ -365,4 +365,8 @@ MigrationBackup/
 .ionide/

 # Fody - auto-generated XML schema
-FodyWeavers.xsd
+FodyWeavers.xsd
+
+# DocFX
+_site
+docs/api
--- a/README.md
+++ b/README.md
@ -6,11 +6,13 @@
 [![NuGet Version](https://img.shields.io/nuget/v/xdg.directories?style=for-the-badge&logo=nuget)](https://www.nuget.org/packages/Xdg.Directories/)
 [![MIT License](https://img.shields.io/github/license/xdg-net/xdg.directories?style=for-the-badge)](https://choosealicense.com/licenses/mit/)

-Xdg.Net is a ***small*** (the .dll is only 11 KB), [***fast***](./src/Xdg.Benchmarks/README.md) and ***portable*** (Completely supports .NET Standard 2.0 and even NativeAOT!) .NET implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) and XDG user directories for Windows, MacOS and Linux/FreeBSD.
+Xdg.Net is a ***small*** (the .dll is only 11 KB), [***fast***](https://xdg-net.github.io/Xdg.Directories/dev/bench/) and ***portable*** (Completely supports .NET Standard 2.0 and even NativeAOT!) .NET implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) and XDG user directories for Windows, MacOS and Linux/FreeBSD.
+
+Full documentation can be found at <https://xdg-net.github.io/Xdg.Directories/>

 ## Installation

-Use [NuGet](http://docs.nuget.org/docs/start-here/installing-nuge) to install [Xdg.Directories](thttps://www.nuget.org/packages/Xdg.Directories).
+Use [NuGet](http://docs.nuget.org/docs/start-here/installing-nuget) to install [Xdg.Directories](thttps://www.nuget.org/packages/Xdg.Directories).

 From the .NET CLI:

@ -30,9 +32,9 @@ Preview releases are uploaded to both [GitHub packages](https://github.com/xdg-n

 ## Usage

-### Base Directories, C#
+### Base Directories, C\#

-```csharp
+```cs
 using System;
 using Xdg.Directories;

@ -43,7 +45,7 @@ Console.Writeline(BaseDirectory.DataHome);
 Console.Writeline(BaseDirectory.CacheHome)
 ```

-### User Directories, F#
+### User Directories, F\#

 ```fsharp
 open Xdg.Directories
@ -52,57 +54,11 @@ open Xdg.Directories
 printfn "%s" UserDirectory.DesktopDir
 ```

-## Default Locations
-
-If any of the respective XDG environment are specified, the variable will always be returned.
-Otherwise, the value depends on the operating system.
-
-Inspiration is taken from the [Go implementation](https://github.com/adrg/xdg) for Windows and MacOS directories.
-
-<details open>
-<summary>Base Directory</summary>
-
-| Environment Variable | Windows | macOS | Linux/FreeBSD |
-| --- | --- | --- | --- |
-| `XDG_DATA_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.local/share` |
-| `XDG_CONFIG_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.config` |
-| `XDG_STATE_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.local/state` |
-| `XDG_BIN_HOME` | `null` | `null` | `$HOME/.local/bin` |
-| `XDG_DATA_DIRS` | `%APPDATA%:%PROGRAMDATA%` | `/Library/Application Support` | `/usr/local/share:/usr/share` |
-| `XDG_CONFIG_DIRS` | `%LOCALAPPDATA%` | `$HOME/Library/Preferences:/Library/Application Support:/Library/Preferences` | `/etc/xdg` |
-| `XDG_CACHE_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.config` |
-| `XDG_RUNTIME_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `/run/user/$UID` |
-</details>
-
-<details open>
-<summary>User Directory</summary>
-
-User directories on Windows use [Known Folders](https://learn.microsoft.com/en-us/windows/win32/shell/known-folders).
-| Environment Variable | Windows | macOS | Linux/FreeBSD |
-| --- | --- | --- | --- |
-| `XDG_DESKTOP_DIR` | `Desktop` | `$HOME/Desktop` | `$HOME/Desktop` |
-| `XDG_DOWNLOAD_DIR` | `null` | `$HOME/Downloads` | `$HOME/Downloads` |
-| `XDG_DOCUMENTS_DIR` | `My Documents` | `$HOME/Documents` | `$HOME/Documents` |
-| `XDG_MUSIC_DIR` | `My Music` | `$HOME/Music` | `$HOME/Music` |
-| `XDG_PICTURES_DIRS` | `My Pictures` | `$HOME/Pictures` | `$HOME/Pictures` |
-| `XDG_VIDEOS_DIR` | `My Videos` | `$HOME/Movies` | `$HOME/Videos` |
-| `XDG_TEMPLATES_DIR` | `Templates` | `$HOME/Templates` | `$HOME/Templates` |
-| `XDG_PUBLICSHARE_DIR` | `%PUBLIC%` | `$HOME/Public` | `$HOME/Public` |
-</details>
-
-<details open>
-<summary>Extra Directories</summary>
-
-| | Windows | macOS | Linux/FreeBSD |
-| --- | --- | --- | --- |
-| Home | `%USERPROFILE%` | `$HOME` | `$HOME` |
-</details>
-
 ### Native Library (WIP)

 [View the README here](./src/Xdg.Directories.FFI/README.md)

 ## License

-[MIT](https://choosealicense.com/licenses/mit/) \
-Icon is made by Emoji One, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0), via [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Eo_circle_purple_white_letter-x.svg)
+This project is licensed under the [MIT](https://choosealicense.com/licenses/mit/) license. \
+Icon is made by Emoji One, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0), via [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Eo_circle_purple_white_letter-x.svg) an image.
--- a/docs/custom/public/main.js
+++ b/docs/custom/public/main.js
@ -0,0 +1,10 @@
+export default {
+	defaultTheme: 'dark',
+	iconLinks: [
+		{
+			icon: 'github',
+			href: 'https://github.com/xdg-net/Xdg.Net',
+			title: 'GitHub'
+		}
+	]
+}
--- a/docs/docfx.json
+++ b/docs/docfx.json
@ -0,0 +1,49 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/Xdg.Directories*.csproj"
+          ]
+        }
+      ],
+      "dest": "api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern",
+      "custom"
+    ],
+    "globalMetadata": {
+      "_appName": "Xdg.Directories",
+      "_appTitle": "",
+      "_appFaviconPath": "images/icon.png",
+      "_appLogoPath": "images/icon.svg",
+      "_enableSearch": true,
+      "_lang": "en",
+      "pdf": false
+    }
+  }
+}
--- a/docs/docs/defaults.md
+++ b/docs/docs/defaults.md
@ -0,0 +1,48 @@
+# Default Locations
+
+If any of the respective XDG environment are specified, the variable will always be returned.
+Otherwise, the value depends on the operating system.
+
+Inspiration is taken from the [Go implementation](https://github.com/adrg/xdg) for Windows and MacOS directories.
+
+<details open>
+<summary>Base Directory</summary>
+
+| Environment Variable | Windows | macOS | Linux/FreeBSD |
+| --- | --- | --- | --- |
+| `XDG_DATA_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.local/share` |
+| `XDG_CONFIG_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.config` |
+| `XDG_STATE_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.local/state` |
+| `XDG_BIN_HOME` | `null` | `null` | `$HOME/.local/bin` |
+| `XDG_DATA_DIRS` | `%APPDATA%:%PROGRAMDATA%` | `/Library/Application Support` | `/usr/local/share:/usr/share` |
+| `XDG_CONFIG_DIRS` | `%LOCALAPPDATA%` | `$HOME/Library/Preferences:/Library/Application Support:/Library/Preferences` | `/etc/xdg` |
+| `XDG_CACHE_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `$HOME/.config` |
+| `XDG_RUNTIME_HOME` | `%LOCALAPPDATA%` | `$HOME/Library/Application Support` | `/run/user/$UID` |
+</details>
+
+<details open>
+<summary>User Directory</summary>
+
+User directories on Windows use [Known Folders](https://learn.microsoft.com/en-us/windows/win32/shell/known-folders).
+
+Environment Variable | Windows | macOS | Linux/FreeBSD |
+| --- | --- | --- | --- |
+| `XDG_DESKTOP_DIR` | `Desktop` | `$HOME/Desktop` | `$HOME/Desktop` |
+| `XDG_DOWNLOAD_DIR` | `null` | `$HOME/Downloads` | `$HOME/Downloads` |
+| `XDG_DOCUMENTS_DIR` | `My Documents` | `$HOME/Documents` | `$HOME/Documents` |
+| `XDG_MUSIC_DIR` | `My Music` | `$HOME/Music` | `$HOME/Music` |
+| `XDG_PICTURES_DIRS` | `My Pictures` | `$HOME/Pictures` | `$HOME/Pictures` |
+| `XDG_VIDEOS_DIR` | `My Videos` | `$HOME/Movies` | `$HOME/Videos` |
+| `XDG_TEMPLATES_DIR` | `Templates` | `$HOME/Templates` | `$HOME/Templates` |
+| `XDG_PUBLICSHARE_DIR` | `%PUBLIC%` | `$HOME/Public` | `$HOME/Public` |
+</details>
+
+<details open>
+<summary>Extra Directories</summary>
+
+| | Windows | macOS | Linux/FreeBSD |
+| --- | --- | --- | --- |
+| Home | `%USERPROFILE%` | `$HOME` | `$HOME` |
+| Applications | `Programs`, `Common Programs` | `/Applications` | `$XDG_DATA_HOME/applications`, `$HOME/.local/share/applications`, `/usr/local/share/applications`, `/usr/share/applications` |
+| Fonts | `%SYSTEMROOT%\Fonts`, `%LOCALAPPDATA%\Microsoft\Windows\Fonts` | `$HOME/Library/Fonts`, `/Library/Fonts`, `/System/Library/Fonts`, `/Network/Library/Fonts` | `$XDG_DATA_HOME/fonts`, `$HOME/.fonts`, `$HOME/.local/share/fonts`, `/usr/local/share/fonts`, `/usr/share/fonts` |
+</details>
--- a/docs/docs/installation.md
+++ b/docs/docs/installation.md
@ -0,0 +1,28 @@
+# Installation
+
+## Stable Releases
+
+Use [NuGet](http://docs.nuget.org/docs/start-here/installing-nuget) to install [Xdg.Directories](https://www.nuget.org/packages/Xdg.Directories).
+
+From the .NET CLI:
+
+```bash
+dotnet add package Xdg.Directories
+```
+
+or from Visual Studio's package manager:
+
+```pwsh
+Install-Package Xdg.Directories
+```
+
+## Pre-releases
+
+For bleeding edge users, preview releases are available.
+
+They are uploaded to two places automatically every commit:
+
+- [GitHub packages](https://github.com/xdg-net/Xdg.Directories/pkgs/nuget/Xdg.Directories) - A GitHub account is needed to download.
+- [Forgejo packages](https://git.froth.zone/mirrors/-/packages/nuget/xdg.directories) - No login required.
+
+Follow the directions at the respective links to install the package.
--- a/docs/docs/quick-use.md
+++ b/docs/docs/quick-use.md
@ -0,0 +1,22 @@
+# TL;DR
+
+Add the Xdg.Directories package to your project:
+
+```bash
+dotnet add package Xdg.Directories
+```
+
+Then use the `BaseDirectory` and `UserDirectory` classes to access the XDG directories:
+
+```csharp
+using System;
+using Xdg.Directories;
+
+// Prints /home/$USER/.local/share
+Console.Writeline(BaseDirectory.DataHome);
+
+// Prints /home/$USER/Documents
+Console.Writeline(UserDirectory.DocumentsDir);
+```
+
+For more information, see the [API documentation](/api/Xdg.Directories.html).
--- a/docs/docs/toc.yml
+++ b/docs/docs/toc.yml
@ -0,0 +1,4 @@
+- name: Using the Library
+- href: defaults.md
+- href: quick-use.md
+- href: installation.md
--- a/docs/images/icon.png
+++ b/docs/images/icon.png
@ -0,0 +1 @@
+../../icon.png
--- a/docs/images/icon.svg
+++ b/docs/images/icon.svg
@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="40px"
+	height="40px" viewBox="0 0 50 50" version="1.1">
+	<g id="surface1">
+		<path style=" stroke:none;fill-rule:nonzero;fill:rgb(100%,100%,100%);fill-opacity:1;"
+			d="M 48.4375 25 C 48.4375 37.945312 37.945312 48.4375 25 48.4375 C 12.054688 48.4375 1.5625 37.945312 1.5625 25 C 1.5625 12.054688 12.054688 1.5625 25 1.5625 C 37.945312 1.5625 48.4375 12.054688 48.4375 25 Z M 48.4375 25 " />
+		<path
+			style=" stroke:none;fill-rule:nonzero;fill:rgb(36.862745%,20.784314%,69.411765%);fill-opacity:1;"
+			d="M 25 1.5625 C 12.054688 1.5625 1.5625 12.054688 1.5625 25 C 1.5625 37.945312 12.054688 48.4375 25 48.4375 C 37.945312 48.4375 48.4375 37.945312 48.4375 25 C 48.4375 12.054688 37.945312 1.5625 25 1.5625 M 29.308594 36.335938 L 25 28.605469 L 20.449219 36.335938 L 14.941406 36.335938 L 22.230469 24.785156 L 15.296875 13.667969 L 20.957031 13.667969 L 25 21.046875 L 29.152344 13.667969 L 34.628906 13.667969 L 27.691406 24.601562 L 35.058594 36.335938 Z M 29.308594 36.335938 " />
+	</g>
+</svg>
--- a/docs/index.md
+++ b/docs/index.md
@ -0,0 +1,18 @@
+---
+_layout: landing
+---
+
+# Xdg.Directories
+
+> *Want to get straight to the point? Check out the [quick start guide](docs/quick-use.md).*
+
+Xdg.Directories is a library that simplifies using the XDG Base Directory Specification and XDG user directories in .NET applications.
+
+## Features
+
+- **Cross-platform**: Supports Windows, MacOS and Linux/FreeBSD.
+- **Fast**: The .dll is only 11 KB.
+- **Portable**: Completely supports .NET Standard 2.0 and even NativeAOT!
+- **Simple**: Easy to use API.
+- **Sane Defaults**: Provides default directories for when the XDG environment variables are not set.
+  - These defaults are documented in the code itself and are also available [here](docs/defaults.md).
--- a/docs/toc.yml
+++ b/docs/toc.yml
@ -0,0 +1,6 @@
+- name: Docs
+  href: docs/
+- name: API
+  href: api/
+- name: Benchmarks
+  href: dev/bench/
--- a/src/Xdg.Benchmarks/Program.fs
+++ b/src/Xdg.Benchmarks/Program.fs
@ -20,8 +20,8 @@ type Benchmarks() =
    //member _.StateHome () = BaseDirectory.StateHome
    //[<Benchmark>]
    //member _.BinHome () = BaseDirectory.BinHome
-    //[<Benchmark>] 
-    //member _.DataDirs () = BaseDirectory.DataDirs
+    [<Benchmark>] 
+    member _.DataDirs () = BaseDirectory.DataDirs
    // [<Benchmark>]
    // member _.ConfigDirs () = BaseDirectory.ConfigDirs
    //[<Benchmark>]
@ -30,8 +30,8 @@ type Benchmarks() =
    //member _.RuntimeDir() = BaseDirectory.RuntimeDir

    // User Directories
-    // [<Benchmark>]
-    // member _.DesktopDir () = UserDirectory.DesktopDir
+    [<Benchmark>]
+    member _.DesktopDir () = UserDirectory.DesktopDir
    //[<Benchmark>]
    //member _.DownloadDir () = UserDirectory.DownloadDir
    //[<Benchmark>]
@ -48,8 +48,8 @@ type Benchmarks() =
    //member _.PublicDir () = UserDirectory.PublicDir

    // Other
-    // [<Benchmark>]
-    // member _.Home () = Other.Home
+    [<Benchmark>]
+    member _.Home () = Other.Home
    //[<Benchmark>]
    //member _.Applications () = Other.Applications
    //[<Benchmark>]
--- a/src/Xdg.Directories/BaseDirectory.cs
+++ b/src/Xdg.Directories/BaseDirectory.cs
@ -1,9 +1,9 @@
 namespace Xdg.Directories;

-/// <include file='docs/BaseDirectory.xml' path='docs/BaseDirectory'/>
+/// <include file='docs/BaseDirectory.xml' path='docs/BaseDirectory/*'/>
 public static class BaseDirectory
 {
-    /// <include file='docs/BaseDirectory.xml' path='docs/DataHome'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/DataHome/*'/>
    public static string DataHome
    {
        get =>
@ -19,7 +19,7 @@ public static class BaseDirectory
            };
    }

-    /// <include file='docs/BaseDirectory.xml' path='docs/ConfigHome'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/ConfigHome/*'/>
    public static string ConfigHome
    {
        get =>
@ -35,7 +35,7 @@ public static class BaseDirectory
            };
    }

-    /// <include file='docs/BaseDirectory.xml' path='docs/StateHome'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/StateHome/*'/>
    public static string StateHome
    {
        get =>
@ -51,7 +51,7 @@ public static class BaseDirectory
            };
    }

-    /// <include file='docs/BaseDirectory.xml' path='docs/BinHome'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/BinHome/*'/>
    public static string BinHome
    {
        get =>
@ -65,7 +65,7 @@ public static class BaseDirectory
            };
    }

-    /// <include file='docs/BaseDirectory.xml' path='docs/DataDirs'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/DataDirs/*'/>
    public static IList<string> DataDirs
    {
        get =>
@ -73,20 +73,20 @@ public static class BaseDirectory
            ?? Helpers.GetCurrentOperatingSystem() switch
            {
                Helpers.OS.Windows
-                    => new string[]
-                    {
+                    =>
+                    [
                        GetEnvironmentVariable("APPDATA")
                            ?? GetFolderPath(SpecialFolder.ApplicationData),
                        GetEnvironmentVariable("PROGRAMDATA")
                            ?? GetFolderPath(SpecialFolder.CommonApplicationData)
-                    },
-                Helpers.OS.MacOS => new string[] { "/Library/Application Support" },
-                Helpers.OS.UnixLike => new string[] { "/usr/local/share", "/usr/share" },
-                _ => Array.Empty<string>()
+                    ],
+                Helpers.OS.MacOS => ["/Library/Application Support"],
+                Helpers.OS.UnixLike => ["/usr/local/share", "/usr/share"],
+                _ => []
            };
    }

-    /// <include file='docs/BaseDirectory.xml' path='docs/ConfigDirs'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/ConfigDirs/*'/>
    public static IList<string> ConfigDirs
    {
        get =>
@ -94,26 +94,26 @@ public static class BaseDirectory
            ?? Helpers.GetCurrentOperatingSystem() switch
            {
                Helpers.OS.Windows
-                    => new string[]
-                    {
+                    =>
+                    [
                        GetEnvironmentVariable("ProgramData")
                            ?? GetFolderPath(SpecialFolder.CommonApplicationData),
                        GetEnvironmentVariable("APPDATA")
                            ?? GetFolderPath(SpecialFolder.ApplicationData)
-                    },
+                    ],
                Helpers.OS.MacOS
-                    => new string[]
-                    {
+                    =>
+                    [
                        Path.Combine(Other.Home, "Library", "Preferences"),
                        "/Library/Application Support",
                        "/Library/Preferences"
-                    },
-                Helpers.OS.UnixLike => new string[] { "/etc/xdg" },
-                _ => Array.Empty<string>()
+                    ],
+                Helpers.OS.UnixLike => ["/etc/xdg"],
+                _ => []
            };
    }

-    /// <include file='docs/BaseDirectory.xml' path='docs/CacheHome'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/CacheHome/*'/>
    public static string CacheHome
    {
        get =>
@ -130,7 +130,7 @@ public static class BaseDirectory
            };
    }

-    /// <include file='docs/BaseDirectory.xml' path='docs/RuntimeDir'/>
+    /// <include file='docs/BaseDirectory.xml' path='docs/RuntimeDir/*'/>
    public static string RuntimeDir
    {
        get =>
--- a/src/Xdg.Directories/Other.cs
+++ b/src/Xdg.Directories/Other.cs
@ -1,9 +1,9 @@
 namespace Xdg.Directories;

-/// <include file='docs/Other.xml' path='docs/Other'/>
+/// <include file='docs/Other.xml' path='docs/Other/*'/>
 public static class Other
 {
-    /// <include file='docs/Other.xml' path='docs/Home'/>
+    /// <include file='docs/Other.xml' path='docs/Home/*'/>
    public static string Home
    {
        get
@ -19,66 +19,66 @@ public static class Other
        }
    }

-    /// <include file='docs/Other.xml' path='docs/Applications'/>
+    /// <include file='docs/Other.xml' path='docs/Applications/*'/>
    public static IList<string> Applications
    {
        get =>
            Helpers.GetCurrentOperatingSystem() switch
            {
                Helpers.OS.Windows
-                    => new string[]
-                    {
+                    =>
+                    [
                        GetFolderPath(SpecialFolder.Programs),
                        GetFolderPath(SpecialFolder.CommonPrograms)
-                    },
-                Helpers.OS.MacOS => new string[] { "/Applications" },
+                    ],
+                Helpers.OS.MacOS => ["/Applications"],
                Helpers.OS.UnixLike
-                    => new string[]
-                    {
+                    =>
+                    [
                        $"{BaseDirectory.DataHome}/applications",
                        $"{Home}/.local/share/applications",
                        "/usr/local/share/applications",
                        "/usr/share/applications",
                        // TODO: Add $XDG_DATA_DIRS/applications
-                    },
+                    ],
                _ => Array.Empty<string>()
            };
    }

-    /// <include file='docs/Other.xml' path='docs/Fonts'/>
+    /// <include file='docs/Other.xml' path='docs/Fonts/*'/>
    public static IList<string> Fonts
    {
        get =>
            Helpers.GetCurrentOperatingSystem() switch
            {
                Helpers.OS.Windows
-                    => new string[]
-                    {
+                    =>
+                    [
                        GetEnvironmentVariable("SystemRoot") is not null
                            ? $"{GetEnvironmentVariable("SystemRoot")}\\Fonts"
                            : GetFolderPath(SpecialFolder.Fonts),
                        GetEnvironmentVariable("LOCALAPPDATA") is not null
                            ? $"{GetEnvironmentVariable("LOCALAPPDATA")}\\Microsoft\\Windows\\Fonts"
                            : $"{GetFolderPath(SpecialFolder.LocalApplicationData)}\\Microsoft\\Windows\\Fonts"
-                    },
+                    ],
                Helpers.OS.MacOS
-                    => new string[]
-                    {
+                    =>
+                    [
                        $"{Home}/Library/Fonts",
                        "/Library/Fonts",
                        "/System/Library/Fonts",
                        "/Network/Library/Fonts"
-                    },
+                    ],
                Helpers.OS.UnixLike
-                    => new string[]
-                    {
+                    =>
+                    [
                        Path.Combine(BaseDirectory.DataHome, "fonts"),
                        Path.Combine(Home, ".fonts"),
                        Path.Combine(Home, ".local", "share", "fonts"),
                        "/usr/local/share/fonts",
                        "/usr/share/fonts",
                        // TODO: Add $XDG_DATA_DIRS/fonts
-                    },
+                    ],
                _ => Array.Empty<string>()
            };
    }
--- a/src/Xdg.Directories/UserDirectory.cs
+++ b/src/Xdg.Directories/UserDirectory.cs
@ -1,9 +1,9 @@
 namespace Xdg.Directories;

-/// <include file='docs/UserDirectory.xml' path='docs/UserDirectory'/>
+/// <include file='docs/UserDirectory.xml' path='docs/UserDirectory/*'/>
 public static class UserDirectory
 {
-    /// <include file='docs/UserDirectory.xml' path='docs/DesktopDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/DesktopDir/*'/>
    public static string DesktopDir
    {
        get =>
@ -17,7 +17,7 @@ public static class UserDirectory
            };
    }

-    /// <include file='docs/UserDirectory.xml' path='docs/DownloadDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/DownloadDir/*'/>
    public static string DownloadDir
    {
        get =>
@ -32,7 +32,7 @@ public static class UserDirectory
            };
    }

-    /// <include file='docs/UserDirectory.xml' path='docs/DocumentsDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/DocumentsDir/*'/>
    public static string DocumentsDir
    {
        get =>
@ -46,7 +46,7 @@ public static class UserDirectory
            };
    }

-    /// <include file='docs/UserDirectory.xml' path='docs/MusicDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/MusicDir/*'/>
    public static string MusicDir
    {
        get =>
@ -60,7 +60,7 @@ public static class UserDirectory
            };
    }

-    /// <include file='docs/UserDirectory.xml' path='docs/PicturesDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/PicturesDir/*'/>
    public static string PicturesDir
    {
        get =>
@ -74,7 +74,7 @@ public static class UserDirectory
            };
    }

-    /// <include file='docs/UserDirectory.xml' path='docs/VideosDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/VideosDir/*'/>
    public static string VideosDir
    {
        get =>
@ -88,7 +88,7 @@ public static class UserDirectory
            };
    }

-    /// <include file='docs/UserDirectory.xml' path='docs/TemplatesDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/TemplatesDir/*'/>
    public static string TemplatesDir
    {
        get =>
@ -102,7 +102,7 @@ public static class UserDirectory
            };
    }

-    /// <include file='docs/UserDirectory.xml' path='docs/PublicDir'/>
+    /// <include file='docs/UserDirectory.xml' path='docs/PublicDir/*'/>
    public static string PublicDir
    {
        get =>
--- a/src/Xdg.Directories/docs/BaseDirectory.xml
+++ b/src/Xdg.Directories/docs/BaseDirectory.xml
@ -9,9 +9,8 @@
 				<br />
 				This allows users to have less clutter in their home directories, and allows programmers to not have to hard-code directories.
 			</para>
-			All operating systems that are supported by .NET (Windows, macOS, Linux, FreeBSD at the time of writing) are supported.
 			<br />
-			For all base directory files, the directories are resolved as follows:
+			For all base directories, the directories are resolved as follows:
 			<list type="number">
 				<item>
 					<term>
@ -21,7 +20,7 @@
 				</item>
 				<item>
 					<list type="table">
-						<item>Operating systemd dependent fallback:</item>
+						<item>Operating system dependent fallback:</item>
 						<item>
 							<term>Windows</term>
 							<description>
--- a/src/Xdg.Directories/docs/Other.xml
+++ b/src/Xdg.Directories/docs/Other.xml
@ -4,6 +4,10 @@
 		<summary>
 			Other useful directories that aren't specified by XDG.
 		</summary>
+		<remarks>
+			These variables were graciously stolen from the excellent <see href="https://github.com/adrg/xdg">Go XDG implementation</see>.
+			That library largely inspired this one, absolutely recommended if you're working in Go.
+		</remarks>
 	</Other>
 	<Home>
 		<summary>
--- a/src/Xdg.Directories/docs/UserDirectory.xml
+++ b/src/Xdg.Directories/docs/UserDirectory.xml
@ -2,8 +2,40 @@
 <docs>
 	<UserDirectory>
 		<summary>
-			Well-known user directories like desktop, documents and music folders.
+			User directories are "well known" user directories, examples include the Desktop folder and the Documents folder.
 		</summary>
+		<remarks>
+			For all user directories, the directories are resolved as follows:
+			<list type="number">
+				<item>
+					<term> The respective <c>XDG_*</c> enivronment variable </term>
+					<description>will always be used if specified</description>
+				</item>
+				<item>
+					<list type="table">
+						<item>Operating system dependent fallback:</item>
+						<item>
+							<term>Windows</term>
+							<description>
+								Use <see href="https://learn.microsoft.com/en-us/windows/win32/shell/known-folders">Known Folders</see>.
+							</description>
+						</item>
+						<item>
+							<term>macOS</term>
+							<description>
+								Not sure where this is documented by Apple but it largely follows what Linux does.
+							</description>
+						</item>
+						<item>
+							<term>Linux/FreeBSD</term>
+							<description>
+								Follow what <see href="https://freedesktop.org/wiki/Software/xdg-user-dirs">xdg-user-dirs</see> sets.
+							</description>
+						</item>
+					</list>
+				</item>
+			</list>
+		</remarks>
 	</UserDirectory>
 	<DesktopDir>
 		<summary>