dotnet-docfx

name

dotnet-docfx

description

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 (including private ones and any nested type or enum member) — generate any missing or incomplete XML doc comments grounded in the actual code and current changes, then attempt a best-effort documentation report via DocFX (https://dotnet.github.io/docfx/). Invoke as `/dotnet-docfx <TypeName1,TypeName2,...>` (or file paths), or `/dotnet-docfx` with no argument to scope to types touched by uncommitted changes plus commits on the current branch not yet on the base branch. Checks whether the `docfx` .NET tool is installed and attempts to install it (`dotnet tool install -g docfx`) if it isn't; if installation fails, documenting the code still proceeds, but no HTML documentation report is generated and the user is warned explicitly. Works against any .NET/C# project — it discovers the project's own doc-comment conventions rather than assuming a fixed style. Use whenever the user wants XML doc-comment completeness checked and filled in for specific types, instead of relying on a full DocFX site build to surface gaps.

.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/grep across 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> to xunit, NUnit, or MSTest.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 .cs file touched by uncommitted changes plus commits on the current branch not yet on the base branch, same approach as the update-docs skill:

  git status
  git diff <base-branch>...HEAD --name-only
  git diff --name-only
  

  (determine the base branch via git symbolic-ref refs/remotes/origin/HEAD or git branch -a if unclear; ask the user only if genuinely ambiguous). Filter the changed-file list to .cs files, excluding test projects (same detection as above), generated files (any file starting with an <auto-generated comment, or named *.Designer.cs, *.g.cs, *.g.i.cs), and obj/bin output 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-level README, or a CONTRIBUTING file) for any stated doc-comment convention.
• Check each in-scope project's .csproj for <GenerateDocumentationFile>true</GenerateDocumentationFile> — this makes the compiler emit CS1591 ("missing XML comment for publicly visible type or member") warnings, and check whether <WarningsAsErrors> or <TreatWarningsAsErrors> promotes CS1591 to a build failure. This tells you whether public API doc comments are actually enforced, not just conventional.
• Check for a StyleCop Analyzers config (.editorconfig or stylecop.json) for the SA16xx documentation rules (SA1600 types, SA1602 enum items, etc.) and whether they're set to warning/error or suppressed, and whether documentationRules.documentPrivateElements/documentInternalElements is set in stylecop.json.
• Check for a docfx.json at the repository root or under a docs/ folder — its metadata[].src and any filterConfig.yml/ApiRules.filter.yml it references can exclude internal/private members 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 readonly constant, 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> unless void/Task with 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 NamespaceDoc type (grep -r "class NamespaceDoc" --include=*.cs) or a docfx.json build.overwrite folder 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 -p for 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 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.json at the repository root or under a docs/ folder. If none exists, scaffold a minimal one next to the solution file:

  docfx init -y
  

  This creates a docfx_project/docfx.json (plus index.md, toc.yml) pointing metadata[].src at **/*.csproj by default — adjust its src glob if the repository layout needs it (e.g. to exclude test projects, matching the same exclusion used in Step 1). If a docfx.json already exists, use it as-is; don't rewrite an existing project's DocFX configuration unless it's clearly broken (e.g. src pointing at a path that no longer exists).
• Run both steps DocFX needs — metadata extraction from the compiled API surface, then the static site build:

  docfx metadata docfx.json
  docfx build docfx.json
  

  (or docfx docfx.json, which runs both in sequence). This mirrors how java-javadoc invokes 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 way CS1591 does 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 default build.dest, or whatever the project's docfx.json overrides it to) — note that path in the report so the user can open _site/index.html.

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 docfx was 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.html or the project's configured build.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.