Move xml doc section #24705
Merged
Move xml doc section #24705
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
BillWagner
force-pushed
the
move-xml-doc-section
branch
2 times, most recently
from
b7eefc6 to
9fe0d79
Compare
BillWagner
force-pushed
the
move-xml-doc-section
branch
from
9fe0d79 to
d8ee22f
Compare
BillWagner
force-pushed
the
move-xml-doc-section
branch
2 times, most recently
from
f5fce17 to
209b55b
Compare
BillWagner
force-pushed
the
move-xml-doc-section
branch
4 times, most recently
from
ca072cf to
21bb9a5
Compare
Move content from all XML documentation files. All the tag reference was combined, but not no other edits were made.
final draft of recommended tags
BillWagner
force-pushed
the
move-xml-doc-section
branch
from
21bb9a5 to
bf25907
Compare
In this commit, I checked all open issues on the XML doc section and made sure they were addressed. Where they have not been, make updates to address them.
Some were incorrectly going to samples instead of the description of each tag.
Use the clean-repo tool to replace links that have been redirected.
Run the clean-repo tool to replace root links with relative links.
This is showing up in build warnings.
Two redirects weren't formatted correctly. Fix those, and rerun clean-repo to get clean builds.
BillWagner
requested review from
a team,
IEvangelist,
cartermp and
gewarren
as code owners
tdykstra
approved these changes
Jul 16, 2021
Contributor
tdykstra
left a comment
tdykstra
left a comment
There was a problem hiding this comment.
This is great work, a tremendous amount of text and code and all done extremely well. I noted some typos and some opportunities to improve readability - feel free to take or leave any of the suggestions and comments.
Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: Tom Dykstra <tdykstra@microsoft.com>
This was referenced Jul 19, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Rework the XML documentation section and move it into the language reference.
Notes for reviewers:
You should view the three new files under language-reference/xmldoc as all new content. They were taken from existing content, but substantially rearranged and rewritten. The samples and snippets were also consolidated and moved. The final code has a smaller set of samples, but each sample represents a typical scenario: documenting a class or record, inheriting docs from other locations, and generic classes and methods.
Fixes #4176: Examples and recommended content now include an
hrefexample forseeandseealso.Fixes #7622: This content is in the index for this section, which increases its findability. The title has also changed.
Fixes #9355: The examples now include a table for the list tag.
Fixes #15906: Note that
paracreates a double spaced paragraph. Use<br/>for single spacing.Fixes #16204: The
creftag explains how to reference a generic type. The generic examples include an example.Fixes #17326: Specify that
inheritdocfor a type also inherits comments for all members.Fixes #17625: No actual change. Verify that
crefandPathare the only tags to specify the inherited source.Fixes #17796: The introduction to "recommended tags" explains how to escape
<and>in comments.Fixes #18236: This is a duplicate of 18730, and 23533.
Fixes #18659: The "recommended tags" article now lists the relevant tags validated by the compiler.
Fixes #18730: The "recommended tags" article lists which tags are shown in intellisense.
Fixes #18818: Note that some tags cannot be nested, specifically the
seealsotag.Fixes #21885: point out that the
<see>tag can provide alternative text.Fixes #23533: Show examples of
<inheritdoc>that use the path attribute to include only some tags.Internal review site link See the entire section. This is the index.