Dev analyzer to flag `<see cref="...">` XML doc tags to private/internal members
- Dominant language
- C#
- Stars
- 2.4k
- Forks
- 658
- Avg merge
- 3d 5h
- Merged PRs (30d)
- 9
Description
### Is there an existing issue for this?
- [x] I have searched the existing issues
### Task description
There were many cases where we ported or added XML doc comments with `` tags that referenced private/internal (or otherwise non-visible) members. This compiles in C# fine without warning, but causes warnings in the docfx build and broken links in the documentation.
Example: https://lucenenet.apache.org/docs/4.8.0-beta00018/api/analysis-common/Lucene.Net.Analysis.Core.TypeTokenFilter.html#Lucene_Net_Analysis_Core_TypeTokenFilter_Accept
Note that `useWhiteList` and `stopTypes` references are to private fields, so the links are broken. docfx warns about this on build, but due to the vast number of warnings we just haven't worked through them all (though I have a PR coming soon that cleans up many of them).
(Aside: this is even more interesting since the original upstream Java code does not use references for these at all.)
We should create a Lucene.NET dev analyzer that looks for `cref` references to non-publicly-visible members or types from a publicly-visible XML doc comment and flag it as a warning, since it breaks the documentation site links. We can then turn that into an error once fully cleaned up. Note that references to non-publicly-visible members or types from another non-publicly-visible XML doc comment should not fire this analyzer rule; those are fine.
This rule should support all valid forms/syntax of the `` tag, including self-closing, with or without extra spaces, with overriding link text, etc. Documentation: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags#see
As a code fix, we can provide a couple of code fix options for a violation of this rule:
1. Replace reference with [`...` code tag](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags#c) (where the text within the tag is either the cref attribute text or inner text)
2. Replace reference with cref attribute text (or inner text) with no wrapping tag
3. Make member public (although this should be treated with care)
Contributor guide
Research direction
No source files or tests are named; start by locating the existing Lucene.NET dev analyzers and their test entry points, then inspect how XML documentation and docfx warnings are handled. Done means warnings identify non-public cref targets from public documentation, exempt non-public documentation, support the listed see syntaxes, and offer the three described code-fix options.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100