Examples in the headers do not compile

[skipbit]

Several @code blocks use constructs the library does not provide, so a reader who copies them gets a compile error.

path::operator/ does not exist

include/dross/platform.h:27 and :35, and include/dross/platform/xdg.h:40, :46, :52 build paths with /:

path config_dir = path::home().value_or(path{"/tmp"}) / "myapp";

path declares no operator/. Grepping the tree, the only operator/ is number's. The member for joining is append().

A bare string literal is ambiguous

include/dross/platform/path.h:44, :50, :81, :197 and :244 initialise a path from a literal:

path config_path{"~/.config/myapp"};

path has converting constructors from both const std::string& and const std::filesystem::path&, so a const char* argument requires an equally ranked user-defined conversion for each and the call is ambiguous:

error: call of overloaded 'path(<brace-enclosed initializer list>)' is ambiguous

The pages already document this — docs/sphinx/source/api/platform.rst says "A bare string literal is ambiguous between the std::string and the std::filesystem::path constructor, so name the type you mean" — and the copies of these examples there name the type. Only the headers do not.

One more

include/dross/platform/path.h:52 prints "Directory created: " on the success branch of mkdir(), which no longer implies the directory was created: an already-present one is also a success.

Suggestion

Extract each @code block mechanically and compile it, rather than reading it. Copying a block by hand tends to fix these silently.