Docs tracking: examples in the almanac

[WhiteBlackGoose]

The measured state of this is in the comment below, which replaces the checklist that used to be here: it linked two merged pull requests as if they were open work, and marked MathS.* done when it is 146 of 194.

Counted from the generated AngouriMath.xml of a 2.0.0 build:

surface	documented members	with <example>
MathS.*	194	146
Entity and its nodes	980	35
AngouriMath.Extensions	89	0
AngouriMath.Core	237	3
everything else	331	0

In order: AngouriMath.Extensions first, since all 89 have a summary and none has an example and it is the shortest path into the library; then Transformation and RewriteRecording, which are new in 2.0; then the Entity operation surface, which wants its own issue rather than a ratio.

The wiki is the other half of the docs and is tracked separately — it is now machine-checked against a build (86 samples, 0 compile errors, 0 output mismatches).

[Rafael-SOWNet]

Replacing the checklist with a measured one, since the two items it linked are merged pull
requests rather than open work, and the item it marks done is not done.

Counted from the generated AngouriMath.xml of a 2.0.0 build (Sources/AngouriMath/bin/Release/net10.0),
by grouping every documented member and asking whether it carries an <example>:

surface	documented members	with <example>
MathS.*	194	146
Entity and its nodes	980	35
AngouriMath.Extensions	89	0
AngouriMath.Core	237	3
everything else	331	0
total	1831	184

Reproduce with:

dotnet build -c Release Sources/AngouriMath/AngouriMath.csproj
python3 - Sources/AngouriMath/bin/Release/net10.0/AngouriMath.xml <<'PY'
import sys, xml.etree.ElementTree as ET
from collections import Counter
n, e = Counter(), Counter()
def g(x):
    b = x[2:]
    for p in ("MathS", "Entity", "Extensions", "Core"):
        if b.startswith("AngouriMath." + p): return p
    return "other"
for m in ET.parse(sys.argv[1]).find("members"):
    if m.get("name").startswith("T:"): continue
    k = g(m.get("name")); n[k] += 1
    if m.find("example") is not None: e[k] += 1
for k in ("MathS", "Entity", "Extensions", "Core", "other"): print(k, n[k], e[k])
PY

The denominators understate the surface, and deliberately: a member with no XML docs at
all does not appear in that file, so this counts documented members and not public ones. It
is still the right ratio to work from, because a member with no summary needs a summary
before it needs an example.

What is actually left

• MathS.* — 146 of 194. More docs #583 did the bulk; the 48 without an example are worth a
  pass, but this surface is in good shape and is no longer the bottleneck.
• AngouriMath.Extensions — 0 of 89. Every one has a summary and none has an
  example. This is the cheapest and highest-value item left: the extensions are the
  shortest path into the library ("x + 2".Simplify()), and the almanac shows a reader
  nothing to copy.
• Entity — 35 of 980. Not a checkbox: most of those 980 are record members and
  constructors generated per node, and an example on each would be noise. What wants
  examples is the operation surface — Simplify, Solve, Differentiate, Integrate,
  Limit, Substitute, Replace, Compile, Latexize, Stringize, Evaled,
  InnerSimplified, Alternate — and the node types a reader pattern-matches on. Worth
  splitting into its own issue with that list rather than tracking a ratio.
• AngouriMath.Core — 3 of 237. Transformation and RewriteRecording are new in
  2.0 and are the parts a reader cannot guess at, so those two come first.

The other half of the docs, and where it now stands

This issue is about the almanac, which is generated from these XML comments. The wiki is
the other half, and it had drifted further: measured against a 2.0.0 build, 23 of its 90 code
samples did not compile and 9 more printed something other than what their page said. Among
them, Latexise had become Latexize, Exceptions documented a FutureReleaseException
that #872 removed, and the whole F# page called a function `dy/dx` that has always
been `d/dx` while opening three modules by paths that do not resolve — so that sample
had never worked. The website's quickstart had the same fault in the first F# program a new
reader runs.

Those are fixed, and the wiki now compiles and runs clean: 86 samples, 0 compile errors, 0
output mismatches, 57 stated outputs verified. The check is a harness rather than a one-off
pass, so it can be re-run against any build.

It does not run in CI, and until it does the wiki will drift again — the harness lives in
a separate analysis workspace, not in this repository. Moving it here and adding a workflow
step is its own piece of work and is not done.

[Rafael-SOWNet]

Re-measured on master at a45a7256 (2.2.0), by the same script. The picture has changed, and not in the direction the raw counts suggest.

surface	documented	with <example>	was, on 2.0.0
MathS.*	217	147	194 / 146
Entity and its nodes	1271	39	980 / 35
AngouriMath.Extensions	90	0	89 / 0
AngouriMath.Core	376	9	237 / 3
everything else	492	0	331 / 0
total	2446	195	1831 / 184

The documented surface grew by 615 members and the examples grew by 11. So the ratio went from 10.0% to 8.0% — the almanac is falling behind faster than it is being filled, and the raw "+11 examples" reads like progress only until it is put beside the denominator.

Two things follow, and I think they are the useful output of tracking this at all:

AngouriMath.Extensions is still exactly zero of 90, unchanged across a whole release. It is also the surface a caller reaches for first — "x + 1".Simplify() is the extension method, not MathS. If any one row is worth attacking it is that one, and it is 90 members rather than 1271.

MathS.* is 68% and everything else is under 3%. Whatever effort has gone in has gone almost entirely to the one surface that was already best covered. That is worth deciding deliberately rather than by drift: either the goal is MathS.* and the others are out of scope, in which case the checklist should say so, or it is not and the effort is going to the wrong place.

For reference, #961 (non-kernel functions, open) adds three MathS members and all three carry examples, which is 3 of 3 against a baseline of 8% — worth saying only because it is the kind of contribution that moves the ratio rather than the count.