Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature Request] Space missing betweeen: /// and <summary> #9848

Open
Marv51 opened this issue Apr 8, 2024 · 1 comment
Open

[Feature Request] Space missing betweeen: /// and <summary> #9848

Marv51 opened this issue Apr 8, 2024 · 1 comment
Labels
dotnet: xml-comment XML comment for .NET API reference docs

Comments

@Marv51
Copy link

Marv51 commented Apr 8, 2024

Is your feature request related to a problem? Please describe.
I just fixed quite a few instances in our code-base that had documentation comments that were accidentally missing a space between /// and <summary>.
This leads to the summary being quietly ignored for the docfx output. The docfx, c# compiler and VisualStudio are not warning or complaining about this missing space is any way. The description is simply missing in the rendered docfx output.

So instead of /// <summary>This code is great</summary> we had ///<summary>This code is great</summary>.

I understand that all available examples contain this space (including in the c# standard).

Describe the solution you'd like
My suggestion would be to be permissive when parsing, and to treat the space as optional.

Describe alternatives you've considered
The alternative solution for this issue would be to issue a "missing documentation" or even better "missing space"-warning. That would also fully satisfy my request.

Additional context
I can provide a sample/repro, but I believe this is a pretty clear request.

I searched the docfx Issues quite a bit, because I thought somebody must have encountered this before. Sorry, if I missed something and this is a duplicate request.

@filzrev
Copy link
Contributor

filzrev commented Apr 8, 2024

It can be handled by using Stylecop.Analyzer.
By setting rule SA1004: DocumentationLinesMustBeginWithSingleSpace as warning.

Steps

  1. Install StyleCop.Analyzers.Unstable NuGet analyzer packages to project.
  2. Set following settings to .editorconfig file.
dotnet_diagnostic.SA1004.severity = warning # SA1004: A line within a documentation header above a C# element does not begin with a single space.

# TODO: Configure other StyleCopAnalyzer rules to `severity = none`.

@yufeih yufeih added the dotnet: xml-comment XML comment for .NET API reference docs label Apr 10, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dotnet: xml-comment XML comment for .NET API reference docs
Projects
None yet
Development

No branches or pull requests

3 participants