Summary
Per-type documentation generation writes current Markdown pages but does not remove pages produced by earlier builds for types that have since been deleted or renamed.
This allows removed APIs to remain published indefinitely, even after the source class no longer exists and the current XML documentation input no longer contains it.
Observed scenario
- Generate per-type documentation for a project or multi-project solution.
- Remove or rename a public class/interface.
- Rebuild with Xml2Doc using the same output directory.
- Inspect the generated documentation directory.
The old Markdown page remains unless it is deleted manually or the entire output directory is cleaned first.
In the observed solution, pages for removed rendering contracts remained in the authoritative root docs/ tree after their C# files were deleted. This made deleted APIs appear to still be supported.
Expected behavior
Xml2Doc should provide a safe, deterministic way to prune files it previously generated but which are no longer part of the current input set.
It must not delete unrelated hand-authored files that happen to share the output directory.
Actual behavior
Generation is additive/overwrite-only. Obsolete generated pages survive and can remain linked from a previously generated index.
Suggested design
Track ownership of generated files with a manifest in the output directory, for example:
Each successful generation could:
- compute the complete canonical output set;
- write/update current files;
- remove only previously manifested Xml2Doc-owned files that are absent from the new set;
- atomically replace the manifest.
An explicit opt-in such as Xml2Doc_PruneStaleFiles=true could preserve backward compatibility. A dry-run/report mode could list files that would be removed.
For multi-project shared output, manifest ownership must be scoped or aggregated so one project cannot delete another project's pages.
Acceptance criteria
- An integration test generates docs, removes or renames a type, regenerates, and confirms the obsolete page is removed.
- Hand-authored/untracked files in the same directory are preserved.
- Cleanup is deterministic and restricted to Xml2Doc-owned files.
- Failed or partial generation does not leave a corrupted manifest or delete valid pages.
- Multi-project output ownership is explicitly handled.
- Existing behavior remains available by default if pruning is introduced as opt-in.
- README/MSBuild documentation explains cleanup semantics.
Related work
Issues #42 and #45 discuss incremental/diff-oriented generation. Stale-output pruning should coordinate with that work but is a distinct correctness problem.
Summary
Per-type documentation generation writes current Markdown pages but does not remove pages produced by earlier builds for types that have since been deleted or renamed.
This allows removed APIs to remain published indefinitely, even after the source class no longer exists and the current XML documentation input no longer contains it.
Observed scenario
The old Markdown page remains unless it is deleted manually or the entire output directory is cleaned first.
In the observed solution, pages for removed rendering contracts remained in the authoritative root
docs/tree after their C# files were deleted. This made deleted APIs appear to still be supported.Expected behavior
Xml2Doc should provide a safe, deterministic way to prune files it previously generated but which are no longer part of the current input set.
It must not delete unrelated hand-authored files that happen to share the output directory.
Actual behavior
Generation is additive/overwrite-only. Obsolete generated pages survive and can remain linked from a previously generated index.
Suggested design
Track ownership of generated files with a manifest in the output directory, for example:
Each successful generation could:
An explicit opt-in such as
Xml2Doc_PruneStaleFiles=truecould preserve backward compatibility. A dry-run/report mode could list files that would be removed.For multi-project shared output, manifest ownership must be scoped or aggregated so one project cannot delete another project's pages.
Acceptance criteria
Related work
Issues #42 and #45 discuss incremental/diff-oriented generation. Stale-output pruning should coordinate with that work but is a distinct correctness problem.