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.

Sign up for GitHub

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

Jump to bottom

Review our usage of <code> in XML docs #20849

Closed
roji opened this issue May 5, 2020 · 7 comments · Fixed by #20893
Closed

Review our usage of <code> in XML docs #20849

roji opened this issue May 5, 2020 · 7 comments · Fixed by #20893
Assignees
@roji
Labels
area-docs closed-fixed The issue has been fixed and is/will be included in the release indicated by the issue milestone. type-cleanup
Milestone
5.0.0

Comments

@roji
Copy link
Member

roji commented May 5, 2020 •
edited
Loading

It seems like in many cases we expect <code> doc fragments to render inline, but in the docs they're rendered as a block, leading to ugly/mangled docs.

In some cases, a separate code block may make sense, but this needs to be cleaned up...
@ajcvickers
Copy link
Member

@roji Further evidence that we should get rid of them.

@roji
Copy link
Member Author

roji commented May 5, 2020

Not sure it would solve what you think it would - the supporters of <code> would switch to wanting italics instead or something 😆

More seriously, in cases like FromSqlInterpolated a separate code block makes sense to me, but that's not how it's being used at the moment (e.g. there's a dot afterwards...).

@ajcvickers ajcvickers added this to the 5.0.0 milestone May 8, 2020
roji added a commit that referenced this issue May 8, 2020
@roji
Clean up <code> in XML docs
d41af70 
Closes #20849
@roji roji mentioned this issue May 8, 2020
Merged
roji added a commit that referenced this issue May 9, 2020
@roji
Clean up <code> in XML docs (#20893)
daf9cf3 
Closes #20849
@roji
Copy link
Member Author

roji commented May 9, 2020

Reopening to verify that the output looks good (especially with regards to #20893 (review)).

@roji roji reopened this May 9, 2020
@roji
Copy link
Member Author

roji commented May 31, 2020

Closing since we've decided not to push the API docs live for now. We'll revisit this later.

@roji roji closed this as completed May 31, 2020
@sharwell
Copy link
Member

This is easy to review if you use DotNetAnalyzers/DocumentationAnalyzers. I believe DOC203 is the rule that flags misuse of <code> elements, and a code fix is provided to convert them to <c>. Here's the unit test for this specific case.

@roji roji mentioned this issue Jun 1, 2020
Closed
@roji
Copy link
Member Author

roji commented Jun 1, 2020

Thanks @sharwell, opened #21094 to track.

@roji
Copy link
Member Author

roji commented Jun 1, 2020

@sharwell, I'm seeing that the DotNetAnalyzers.DocumentationAnalyzers was last released in 2018, and the latest version is still a beta. Is this the right package, and if so, is it being updated?

@ajcvickers ajcvickers added the closed-fixed The issue has been fixed and is/will be included in the release indicated by the issue milestone. label Jun 1, 2020
@ajcvickers ajcvickers modified the milestones: 5.0.0, 5.0.0-preview6 Jun 1, 2020
@ajcvickers ajcvickers modified the milestones: 5.0.0-preview6, 5.0.0 Nov 7, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@roji roji

Labels
area-docs closed-fixed The issue has been fixed and is/will be included in the release indicated by the issue milestone. type-cleanup
Projects
None yet
Milestone
5.0.0
Development

Successfully merging a pull request may close this issue.

Clean up <code> in XML docs dotnet/efcore
3 participants
@sharwell @ajcvickers @roji