Conversation
|
|
||
| /// <summary> | ||
| /// Gets a value indicating whether the documentation comments are parsed. | ||
| /// Gets a value indicating whether the documentation comments are parsed and can produce diagnostics, parsed only, or treated as regular comments. |
There was a problem hiding this comment.
Consider simply saying: "Gets a value indicating whether the documentation comments are parsed and analyzed."
| /// </summary> | ||
| /// <value><c>true</c> if documentation comments are parsed, <c>false</c> otherwise.</value> | ||
| /// <value> | ||
| /// <para><see cref="DocumentationMode.Diagnose"/> if documentation comments are parsed and can produce diagnostics.</para> |
There was a problem hiding this comment.
Consider saying: "if documentation comments are parsed and analyzed"
| /// <value><c>true</c> if documentation comments are parsed, <c>false</c> otherwise.</value> | ||
| /// <value> | ||
| /// <para><see cref="DocumentationMode.Diagnose"/> if documentation comments are parsed and can produce diagnostics.</para> | ||
| /// <para><see cref="DocumentationMode.Parse"/> if documentation comments are parsed without producing diagnostics.</para> |
There was a problem hiding this comment.
Consider saying: "if documentation comments are parsed, but not analyzed." I am assuming parsing itself can cause some diagnostics to be reported. So, "without producing diagnostics" is probably not accurate.
There was a problem hiding this comment.
The doc for DocumentationMode.Parse says: "Parses documentation comments as structured trivia, but do not report any diagnostics.". I'll try to check if parsing itself can produce diagnostics or not, and update both comments.
There was a problem hiding this comment.
If enum values are documented, then why duplicate the information here at all? This is going to create an unnecessary maintenance burden, in my opinion.
There was a problem hiding this comment.
Sounds reasonable. I'm going to delete the "value" tag.
|
Done with review pass (commit 1) |
|
@dotnet/roslyn-compiler For a second review. |
|
Thanks @Youssef1313! |
Fixes https://github.com/dotnet/roslyn-api-docs/issues/86