-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
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
Use the third person in method docs #6778
Conversation
In my projects I always use no-person references in the method introduction and then the third person in description. E.g: # Set foo to bar. May raise. Uploads to server.
def foo
end So in the docs summary it says Which approach is right? |
According to Documenting code you should always document methods in the third person:
|
src/array.cr
Outdated
@@ -190,7 +190,7 @@ class Array(T) | |||
size <=> other.size | |||
end | |||
|
|||
# Set intersection: returns a new `Array` containing elements common to `self` | |||
# Sets intersection: returns a new `Array` containing elements common to `self` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is actually a noun, not a verb. ("Set intersection", as in the intersection of two sets)
Same below on the next diff line for this file
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Rest is good
src/compiler/crystal/compiler.cr
Outdated
@@ -83,7 +83,7 @@ module Crystal | |||
# one LLVM module is created for each type in a program. | |||
property? single_module = false | |||
|
|||
# Set to a `ProgressTracker` object which tracks compilation progress. | |||
# Sets to a `ProgressTracker` object which tracks compilation progress. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This was correct before, although badly worded (my docs, sorry)
src/compiler/crystal/program.cr
Outdated
@@ -110,7 +110,7 @@ module Crystal | |||
# The main filename of this program | |||
property filename : String? | |||
|
|||
# Set to a `ProgressTracker` object which tracks compilation progress. | |||
# Sets to a `ProgressTracker` object which tracks compilation progress. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ditto
…erson3 this is necessary
* Use the third person * Remove the s from 2 nouns * Remove 2 s'
There are some methods left that don't use the third person.