Clean up doc/dev documentation files
#6195
Open
+180
−173
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
optionsome
reviewed
Oct 27, 2024
Comment on lines
-126
to
+132
| 9. getter and setters | ||
| 8. `private`/package methods | ||
| 10. `private` enums (avoid `public`) | ||
| 11. interfaces | ||
| 12. `private static` classes (avoid `public`) | ||
| 13. instance classes (avoid) | ||
| 9. Getter and setters | ||
| 10. `private`/package methods | ||
| 11. `private` enums (avoid `public`) | ||
| 12. Interfaces | ||
| 13. `private static` classes (avoid `public`) | ||
| 14. Instance classes (avoid) |
There was a problem hiding this comment.
Looks like when I applied #6125 (comment), it somehow messed up the order numbers.
optionsome
reviewed
Oct 27, 2024
| conflicts. Adding fields and methods to the end of the list will cause merge conflicts more often | ||
| than inserting methods and fields in an ordered list. Fields and methods can be sorted in "feature" | ||
| sections or alphabetically, but stick to it and respect it when adding new methods and fields. | ||
| than will inserting methods and fields in an ordered list. Fields and methods can be sorted in |
There was a problem hiding this comment.
Suggested change
| than will inserting methods and fields in an ordered list. Fields and methods can be sorted in | |
| than inserting methods and fields in an ordered list. Fields and methods can be sorted in |
There was a problem hiding this comment.
Correct me if I'm wrong, but I think this word is not needed here.
| are non-null if they are not marked as `@Nullable`. However, there are places where the | ||
| `@Nullable` annotation is missing even if it should have been used. Those can be updated | ||
| to use the `@Nullable` annotation. | ||
| Use of `@NonNull` annotation is not allowed. It should be assumed methods/parameters/fields are |
There was a problem hiding this comment.
Suggested change
| Use of `@NonNull` annotation is not allowed. It should be assumed methods/parameters/fields are | |
| Use of `@Nonnull` annotation is not allowed. It should be assumed methods/parameters/fields are |
There was a problem hiding this comment.
The javax annotation is @Nonnull, Lombok's annotation is @NonNull (although we shouldn't use that one either).
| Naming convention for builders with and without a context. | ||
|
|
||
| #### Graph Build and tests run without a context | ||
| #### Graph builds and tests run without a context |
There was a problem hiding this comment.
I think we probably should stick to title case in all subtitles as well.
|
Thanks a lot for reading through the documentation and fixing all sorts of mistakes. I added a few comments after reading your suggestions. |
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.
Summary
Cleans up miscellaneous typos, grammatical errors, style inconsistencies, etc. in documentation. This will improve readability for those accessing and referencing the docs, especially for new contributors.
There doesn't appear to be a formatter-enforced line length, so this PR uses 80 characters as that seems to be the loose consensus across other Markdown files in this directory. For stylistic choices like list indents or Oxford commas, this PR makes no decision and preserves existing usage. In general, this PR always favors consistency with existing choices over any standardization of style.
For now, I've touched only the
doc/devMarkdown files. I can clean up the Markdown files for other docs as well in the future.