Repository navigation
Docs tracking: examples in the almanac #585
Description
Activity
- added a commit that references this issue
on Jul 15, 2022 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.xmlof a2.0.0build (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 Entityand its nodes980 35 AngouriMath.Extensions89 0 AngouriMath.Core237 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.TransformationandRewriteRecordingare 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,Latexisehad becomeLatexize,Exceptionsdocumented aFutureReleaseException
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.-
- changed the title
[-]Docs tracking issue[/-][+]Docs tracking: examples in the almanac[/+]on Aug 11, 2026 - added 5 commits that reference this issue
on Aug 14, 2026 Re-measured on
masterata45a7256(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 Entityand its nodes1271 39 980 / 35 AngouriMath.Extensions90 0 89 / 0 AngouriMath.Core376 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.Extensionsis 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, notMathS. 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 isMathS.*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
MathSmembers 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.- added a commit that references this issue
on Aug 23, 2026 - added this to the milestone
on Sep 18, 2026 - removed this from the milestone
on Sep 22, 2026
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.xmlof a 2.0.0 build:<example>MathS.*Entityand its nodesAngouriMath.ExtensionsAngouriMath.CoreIn order:
AngouriMath.Extensionsfirst, since all 89 have a summary and none has an example and it is the shortest path into the library; thenTransformationandRewriteRecording, which are new in 2.0; then theEntityoperation 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).