Change documentation style requirement to /++ +/.#2133
Closed
jmdavis wants to merge 1 commit intodlang:masterfrom
Closed
Change documentation style requirement to /++ +/.#2133jmdavis wants to merge 1 commit intodlang:masterfrom
jmdavis wants to merge 1 commit intodlang:masterfrom
Conversation
If we're going to require either /++ +/ or /** */, /++ +/ makes more sense, because it allows for comments to be put into the documentation if need be, whereas /** */ does not, because it doesn't allow comments to nest. And while comments would usually be in code examples inside a documented unit test, sometimes we still need to put code examples directly in the documentation.
Contributor
|
Thanks for your pull request, @jmdavis! Bugzilla referencesYour PR doesn't reference any Bugzilla issue. If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog. |
Member
Author
|
Closing in favor of #2134. |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 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.
If we're going to require either
/++ +/or/** */,/++ +/makes moresense, because it allows for comments to be put into the documentation
if need be, whereas
/** */does not, because it doesn't allow comments tonest. And while comments would usually be in code examples inside a
documented unit test, sometimes we still need to put code examples
directly in the documentation.
I'm all for disallowing stars or pluses on the beginning of documentation lines (they're really annoying IMHO), but if we're going to require
/++ +/or/** */, I very much would prefer/++ +/, and as the commit message points out,/++ +/is objectively better. In most cases, it doesn't matter, and it's personal preference, but in some cases, it really does matter, and in those cases,/++ +/works well, whereas/** */does not. I don't see any advantage to requiring/** */.