Align the documentation with the API the library actually has

[skipbit]

What

The documentation described an API this library does not have. Every code
sample that included a dross header named a path that has never existed, and
most of them called functions that are not declared anywhere. Nothing on the
documentation site compiled except the one snippet in the README.

This rewrites the samples against what the headers declare, and corrects the
prose — including the Doxygen comments the prose was copied from, which turned
out to be the source of several of the errors.

What the samples were saying

The documentation	The library
#include <dross/value.h> and 30 others	include/dross/type/value.h; 31 of 32 include paths named files that are not there
value::is_number() / as_number()	the is<T>() / as<T>() templates
dictionary::set(k, v) / get(k)	operator[], contains()
array::size()	length()
environment::get/set/unset/get_all	one static std::optional<std::string> value()
path::join/absolute/exists/read_file/write_file	mkdir, home, separator, append, expand, resolve, exists
error_code type, parse_json / to_json	neither exists; the format support is TOML

Where the library has an equivalent, the sample now uses it — TOML in place of
JSON, mkdir in place of create_directory, the four xdg accessors reached
through an instance. Where it has none, the lines are gone rather than replaced
with a placeholder. One page went with them: the JSON example, since there is no
JSON entry point to document. Its toctree entry and cross-reference went too.

Verification

Every code block that includes a dross header was extracted and compiled: 22
blocks, twice each, once with Clang 22 against libstdc++ 15 and once with
Clang 20 against libstdc++ 13. All 22 pass in both configurations with
-Wall -Wextra and no warnings from the samples themselves.

The harness adds no headers of its own — a block that needs <iostream> says so
— because a block that only compiles inside a harness is not an example a reader
can use. Five blocks were linked and run to check that their output matches what
the pages claim.

Compiling is not the same as being right, so the claims were checked against the
implementation rather than against the headers. That distinction mattered: the
first pass took its wording from the Doxygen comments, and four of those describe
behaviour the code does not have.

The comment said	The code does
length() counts Unicode code points	returns buffer.size() — UTF-8 bytes. "日本語" is 9
as<T>() on a mismatch is undefined	returns a default-constructed T, and value_cast_wrong_type pins that with EXPECT_EQ
mkdir() succeeds if the directory exists	reports failure; error().code() is zero there and non-zero for real failures
value() yields nullopt for an empty variable	getenv returns non-null for FOO=, so the optional holds ""
number conversions throw std::runtime_error	they return 0, 0.0 and 0LL

Those comments are now corrected too. Only comments changed under include/; no
code moved.

Two implementation faults are written down rather than smoothed over

path::expand() declares std::expected but lets a filesystem_error escape
when canonicalisation fails — a missing target, a permission problem, a symlink
loop. resolve() catches the same condition. Measured: the process terminates
with SIGABRT.

mkdir() treats an existing directory as a failure, and the error it returns
carries no diagnostic code, so what() reads "failed: Success".

The pages say so, and point at resolve() for paths that may not exist yet.
Neither is worked around in the prose as though it were intended behaviour.

Claims that were wider than the code

string is no longer described as Unicode-aware: it holds UTF-8 bytes, and
length(), prefix and equality all work on those bytes, so any of them can split
or match across a multi-byte character. Nothing validates the content either, so
the promise of undefined behaviour on malformed input is gone — the bytes are
kept and handed back as they came.

Four pages said all types are copyable and assignable; environment has all its
special members deleted. Four pages said the library does not use exceptions; the
bounds-checked accessors throw std::out_of_range, and three path operations
reach for throwing filesystem calls. The changelog credited every type with
three-way comparison, where six have it.

The README example

The sweep covered the pages under docs/sphinx/source, so the quick example in
the README was outside it and had never been compiled. It used a braced
initialiser list for dictionary, a static xdg::config_home(), and operator/
on path — none of which exist. It now builds and runs in both configurations,
and mentions in passing why the entries are assigned after construction and why
xdg takes an instance.

What this does not fix

The library has faults that documentation cannot close, and pages that were left
alone. Both are listed rather than left to be found again:

• path::expand() terminating, and mkdir() returning an error with no code
• value{x} wrapping its argument in a one-element array, so a type changes
  silently
• path, xdg and error having no tests, which is why several of these went
  unnoticed
• @code examples in the headers that do not compile, including ones that use
  the operator/ the README no longer uses
• toml.h claiming complete TOML v1.0.0 support, which the serializer does not
  provide

The contributing guide keeps its "no exceptions" rule: it tells contributors how
to write new code, not what the library does. That the library does not follow
it is one of the faults above.