iru-dotnet-docfx
Audit given C# class(es)/type(s) for complete XML doc-comment coverage — type-level `<summary>` (and `<typeparam>` for generics), every field/property/constant/event, every constructor/method (includi
SKILL.md.claude/skills/iru-dotnet-docfx/SKILL.md
GitHub.NET DocFX
Make sure a set of C# types — and the DocFX site built from them — carry complete, well-formed XML doc comments,
filling in whatever is missing, then attempt to prove the result actually builds via DocFX. This skill only
adds/completes /// doc comments — it does not change behavior, signatures, or non-doc-comment code. Test classes
are out of scope for documentation requirements — they don't need type/member-level doc comments added, even if
named explicitly — but any doc comment a test class already has must be left as-is; never strip or "clean up"
existing comments in test code. It makes no assumptions about this being any particular repository — discover the
project's actual conventions and build setup fresh each run.
Step 1 — Determine scope
- Argument provided (comma-separated type names or file paths): resolve each to its file. If given a simple
type name, locate it via
find/grepacross the whole repository (every.csproj's source, not just one project) rather than guessing the namespace/project. If a resolved file turns out to live in a test project (containing a<PackageReference>toxunit,NUnit, orMSTest.TestFramework, or named like*.Tests/*.UnitTests/*.IntegrationTests), drop it from the scope audited/generated in Steps 2-5 — say so in the Step 8 report rather than silently ignoring it — since test classes carry no doc-comment requirement here. - No argument: default to every non-test
.csfile touched by uncommitted changes plus commits on the current branch not yet on the base branch, same approach as theiru-update-docsskill:
(determine the base branch viagit status git diff <base-branch>...HEAD --name-only git diff --name-onlygit symbolic-ref refs/remotes/origin/HEADorgit branch -aif unclear; ask the user only if genuinely ambiguous). Filter the changed-file list to.csfiles, excluding test projects (same detection as above), generated files (any file starting with an<auto-generatedcomment, or named*.Designer.cs,*.g.cs,*.g.i.cs), andobj/binoutput directories. - If the resulting scope is empty (no argument and no relevant changes), tell the user there is nothing to document and stop.
- From the in-scope files, derive the distinct set of namespaces and containing projects involved — these feed Step 4, which checks whether this project uses namespace-level documentation at all.
Step 2 — Discover this project's actual doc-comment bar before auditing
Don't assume a fixed documentation scope — discover it from the project itself, since projects vary on whether non-public members need doc comments:
- Check for a contributor guide (
CLAUDE.md,AGENTS.md, a top-levelREADME, or aCONTRIBUTINGfile) for any stated doc-comment convention. - Check each in-scope project's
.csprojfor<GenerateDocumentationFile>true</GenerateDocumentationFile>— this makes the compiler emitCS1591("missing XML comment for publicly visible type or member") warnings, and check whether<WarningsAsErrors>or<TreatWarningsAsErrors>promotesCS1591to a build failure. This tells you whether public API doc comments are actually enforced, not just conventional. - Check for a StyleCop Analyzers config (
.editorconfigorstylecop.json) for theSA16xxdocumentation rules (SA1600types,SA1602enum items, etc.) and whether they're set towarning/erroror suppressed, and whetherdocumentationRules.documentPrivateElements/documentInternalElementsis set instylecop.json. - Check for a
docfx.jsonat the repository root or under adocs/folder — itsmetadata[].srcand anyfilterConfig.yml/ApiRules.filter.ymlit references can excludeinternal/privatemembers from the generated site, which tells you what DocFX itself is actually expected to expose. - If none of the above give a clear answer, skim 2-3 existing types near the ones in scope to see empirically whether non-public members already carry doc comments there — treat that observed practice as the bar, since a stated convention that's looser than what the codebase actually does would leave real gaps unaddressed.
- Reconcile any conflict between a stated convention and the actually-enforced/observed one by following the stricter of the two, so this skill's output would pass the project's own build/analyzer checks.
Skim a couple of existing, well-documented types in the project (prefer ones structurally similar to what's in
scope) to internalize the exact phrasing conventions before writing new doc comments: person and tense used,
whether <summary> sentences end in a period, how <typeparam name="T"> is used, the ordering of <param>/
<returns>/<exception>/<value>, whether <remarks>/<example> sections are used, and whether the project
uses <inheritdoc/> for interface implementations and overrides instead of restating documentation. If the
project has no existing doc comments to learn from, fall back to standard .NET conventions (third person, present
tense, <summary>, <param>, <returns>, <exception> in that order, one sentence summary first).
Step 3 — Audit each in-scope type
Read the full file, then check every one of the following is present, non-empty, and actually describes the member's purpose (not just restates its name), scoped per the bar established in Step 2:
- Type-level: a
<summary>on the class/interface/struct/record/enum/delegate itself, including<typeparam name="...">for each generic type parameter declared on the type. - Fields, constants, and properties: every field,
const/static readonlyconstant, and property (with<value>where the project's convention uses it) within the discovered scope. - Events: every event, with a
<summary>describing when it fires. - Constructors: every constructor within scope, with
<param>for each parameter and<exception>for any exception the constructor can throw, per this project's own argument-validation convention (if one is stated or observed in Step 2). - Methods: every method within scope, with
<param>per parameter,<returns>unlessvoid/Taskwith no result, and<exception>for every exception the method can throw and documents. - Enum members: a
<summary>on each member. - Nested types: recurse into these with the same checks as top-level types.
- Interface implementations / overrides: only require their own full doc comment if Step 2 found this project
actually writes one out (rather than relying on
<inheritdoc/>) — follow whichever this project does. If the project uses<inheritdoc/>, a member missing any doc comment at all still counts as a gap — add<inheritdoc/>there, not a full restatement.
For each item found incomplete or missing entirely, record: the member, what's missing (whole comment vs. a
missing <param>/<returns>/<exception> tag), and its current accessibility.
Step 4 — Namespace-level documentation, if this project already uses it
Unlike Java's package-info.java, C# has no built-in namespace-doc mechanism enforced by the compiler — DocFX
supports one via convention (a NamespaceDoc marker class/type carrying the namespace's <summary>, one per
namespace), but many .NET projects never adopt it. Don't impose it where it doesn't already exist:
- Search the repository for any existing
NamespaceDoctype (grep -r "class NamespaceDoc" --include=*.cs) or adocfx.jsonbuild.overwritefolder with namespace-level markdown overrides. - If the project already uses one of these conventions, extend it: for each namespace touched in scope that lacks a namespace doc (or whose existing one is placeholder-only), add/complete it following the exact same convention and level of detail found elsewhere in the project.
- If the project uses neither, skip this step entirely — don't introduce a new documentation convention as a side effect of this skill — but mention in the Step 8 report that namespace-level docs are available as an option DocFX supports, in case the user wants to adopt it going forward.
Step 5 — Generate the missing XML doc comments
For every gap found in Step 3 (and Step 4, if applicable), write the doc comment directly grounded in:
- The member's actual implementation (parameter usage, return expression, thrown exceptions) — read the method body, don't infer purely from the signature/name.
- Any current uncommitted/branch changes to that member (
git diff/git log -pfor that file/hunk if the member was just added or modified) — if the change altered behavior, the new doc comment must describe the current behavior, not stale prior behavior a name alone might suggest. - The phrasing conventions gathered in Step 2 — match voice, tense, and tag ordering/style exactly so the new comments are indistinguishable from hand-written ones in this codebase.
Apply the edits with the Edit tool. Do not modify code logic, signatures, formatting outside the added comments,
or reorder members — this skill only adds/completes /// doc comments.
Step 6 — Check whether docfx is installed
Run command -v docfx (or docfx --version). If it succeeds, skip to Step 7.
If it's missing, attempt to install it: dotnet tool install -g docfx (requires the .NET SDK, which this being a
.NET project implies is already present). Re-check command -v docfx afterward. If the repository has a tool
manifest (.config/dotnet-tools.json) listing docfx, prefer dotnet tool restore and invoke it as
dotnet docfx … instead. When the .NET SDK isn't installed in a default location (a user-local or CI-cached SDK),
docfx also needs DOTNET_ROOT pointing at that SDK's root — without it the tool can't find a runtime.
If the install attempt fails (e.g. no network access, no .NET SDK on PATH), stop here for the reporting step —
do not attempt any other install method or ask the user to intervene. Documenting the code in Steps 1-5 has
already happened regardless; only the documentation report is skipped. Carry the exact error output from the
failed install into the Step 8 report so the user can see why and install it themselves later.
Step 7 — Attempt the documentation report, if docfx is available
- Locate a
docfx.jsonat the repository root or under adocs/folder. If none exists, scaffold a minimal one next to the solution file:
This creates adocfx init -ydocfx_project/docfx.json(plusindex.md,toc.yml) pointingmetadata[].srcat**/*.csprojby default — adjust itssrcglob if the repository layout needs it (e.g. to exclude test projects, matching the same exclusion used in Step 1). If adocfx.jsonalready exists, use it as-is; don't rewrite an existing project's DocFX configuration unless it's clearly broken (e.g.srcpointing at a path that no longer exists). - Run both steps DocFX needs — metadata extraction from the compiled API surface, then the static site build:
(ordocfx metadata docfx.json docfx build docfx.jsondocfx docfx.json, which runs both in sequence). This mirrors howiru-java-javadocinvokes the Javadoc goal directly rather than through a full site build — only documentation generation is being checked here. - Read the console output for warnings/errors: DocFX reports things like invalid
<see cref="...">/<xref>references, broken links, and duplicate UIDs, naming the offending file. It does not, by itself, warn on a missing<summary>the wayCS1591does at compile time — rely on the Step 3 audit for completeness, and on this build only to confirm the doc comments that exist are well-formed and the site actually builds. - If the build fails or reports warnings tied to files in scope, fix the offending comment(s) and re-run until it succeeds cleanly. Warnings in files outside the current scope are pre-existing — note them in the report but don't fix them unless the user asks.
- On success, the generated static site lands under
_site/(DocFX's defaultbuild.dest, or whatever the project'sdocfx.jsonoverrides it to) — note that path in the report so the user can open_site/index.html. - Windows desktop app repositories (a
WinExeproject withUseWPF/UseWindowsForms/UseWinUI): theiru-setup-windows-appscaffold putsdocfx.jsonat the repository root withmetadata[].srclimited to the UI-free Core project (src/<App>.Core) — the public API worth documenting; the CIdocsjob publishes the result under the Antora site'sapi/. Use that file as-is. Types in scope that live in the app project are still audited and documented (Steps 3–5), but they appear in the generated site only ifdocfx.jsonincludes the app project:- WPF / Windows Forms app project — DocFX metadata extraction works on any host when the project builds with
EnableWindowsTargeting=true(set in the scaffold'sDirectory.Build.props; verified on macOS for WPF). - WinUI app project — metadata extraction needs a build, and a WinUI project builds only on Windows: off Windows,
report the DocFX check for it as unverified (needs Windows) and never widen
docfx.jsonto include it there. Generated XAML partials (*.g.cs,InitializeComponent) and MVVM Toolkit generated members carry their own comments or<inheritdoc/>— never audit them.
- WPF / Windows Forms app project — DocFX metadata extraction works on any host when the project builds with
Step 8 — Report
Per type in scope, state: how many members were already fully documented, how many gaps were found and filled (name each), and their current accessibility. Separately, state per namespace whether namespace-level documentation applies to this project at all (Step 4), and if so, whether it already existed and was complete, was extended, or was newly created.
If any argument resolved to a test class (Step 1), name it and note it was excluded since test classes carry no doc-comment requirement here.
State plainly whether the documentation report was generated:
- If
docfxwas missing and the install attempt failed (Step 6), say so explicitly, show the actual error from the failed install attempt, and make clear that code documentation was still completed — only the report step was skipped. Suggest the user install DocFX themselves (dotnet tool install -g docfx) to generate it later. - If the report was generated (Step 7), state the result (clean or which warnings remain, if any pre-existing ones
were left untouched) and the path to the generated site (
_site/index.htmlor the project's configuredbuild.dest).
Do not run a full CI/site-publish pipeline, fix analyzer issues unrelated to doc comments, or add/modify tests — those are a separate quality/implementation skill's job, if this project has one.
Known quirks
Verified in $TMPDIR/iru-verify/windows/gates/ on macOS 27 (arm64), .NET SDK 10.0.402, DocFX 2.81.0 installed with
dotnet tool install --tool-path <dir> docfx (a local tool path, not global):
- The
iru-setup-windows-applayout — a rootdocfx.jsonwithmetadata[].src=src/<App>.Core(**/*.csproj),destdocfx/api, and a build section renderingdocfx/**.{md,yml}(the generateddocfx/api/*.ymlplus the hand-writtendocfx/index.md/docfx/toc.yml) intobuild/docfx(the folder the docs workflow copies under the Antora site'sapi/):docfx metadata docfx.jsonanddocfx build docfx.jsonboth finished with 0 warnings/0 errors and produced one YAML page per Core type (including a CommunityToolkit.Mvvm view model with generated partial members). - The same metadata step pointed at a WPF app project (
net10.0-windows,EnableWindowsTargetinginDirectory.Build.props) also succeeded on macOS (App,MainWindowpages). - With the SDK in a non-default location,
docfxneededDOTNET_ROOTset to it. - Unverified locally (needs Windows): DocFX metadata for a WinUI project (it doesn't build off Windows).