Android Documentation Guide #8
Open
Conversation
This file contains 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
firefoxqb
suggested changes
Jun 1, 2021
Comment on lines
+2
to
+32
| The following are useful tips and conventions for writing descriptions in doc comments. | ||
|
|
||
| **. Use 3rd person (descriptive) not 2nd person (prescriptive).** | ||
|
|
||
| The description is in 3rd person declarative rather than 2nd person imperative. | ||
| >Gets the label. (preferred) | ||
| >a | ||
| >Get the label. (avoid) | ||
|
|
||
| **. Method descriptions begin with a verb phrase.** | ||
|
|
||
| A method implements an operation, so it usually starts with a verb phrase: | ||
| >Gets the label of this button. (preferred) | ||
| > | ||
| >This method gets the label of this button. | ||
|
|
||
| **. Class/interface/field descriptions can omit the subject and simply state the object.** | ||
|
|
||
| These API often describe things rather than actions or behaviors: | ||
| >A button label. (preferred) | ||
| > | ||
| >This field is a button label. (avoid) | ||
|
|
||
| **. Use "this" instead of "the" when referring to an object created from the current class.** | ||
|
|
||
| For example, the description of the getToolkit method should read as follows: | ||
| >Gets the toolkit for this component. (preferred) | ||
| > | ||
| >Gets the toolkit for the component. (avoid) | ||
|
|
||
| **. OK to use phrases instead of complete sentences, in the interests of brevity.** |
There was a problem hiding this comment.
This is a good practice for all comments. So may be add this part is a separate file as a general "How to write comments" rather than in just android section.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Android Documentation Guide