Repository navigation
Conversation
MildestToucan
left a comment
MildestToucan
left a comment
There was a problem hiding this comment.
Some nitpicks about the text rather than the conventions that may or may not be worth fixing.
The conventions themselves seem very reasonable to me.
|
|
||
| Avoid descriptions such as `The position.` for `pos` or `The result.` for a return value. | ||
|
|
||
| ## Start with a short summary |
There was a problem hiding this comment.
Nit: Only the first line of this section is related to starting with a short summary. The rest of the section is concerned with, respectively: terminology, American vs British English spelling and capitalization.
Either the section could be split, or its title and content could be centred around how to write documentation prose.
|
|
||
| Link when it helps the reader find related documentation; repeating a link on every mention is unnecessary. | ||
|
|
||
| ## Explain parameters and results only when needed |
There was a problem hiding this comment.
Nit: Section overlaps a bit with the section on documenting only where it adds value, which explicitly uses obvious return values as an example of unnecessary documentation.
Unsure on how to remedy this (or if it's worth changing), but having two sections go over "only document when it helps the reader" in different regards feels a bit odd.
|
|
||
| ## Explain parameters and results only when needed | ||
|
|
||
| Use `@param`, `@return`, and `@throws` when they help the reader understand a parameter, result, or failure condition. Repeating information from the prose is fine when it makes the documentation clearer or easier to use. Parameter and return descriptions should be short phrases without an initial capital or final period. |
There was a problem hiding this comment.
| Use `@param`, `@return`, and `@throws` when they help the reader understand a parameter, result, or failure condition. Repeating information from the prose is fine when it makes the documentation clearer or easier to use. Parameter and return descriptions should be short phrases without an initial capital or final period. | |
| Use `@param`, `@return`, and `@throws` when they help the reader understand a parameter, result, or failure condition, respectively. Repeating information from the prose is fine when it makes the documentation clearer or easier to use. Parameter and return descriptions should be short phrases without an initial capital or final period. |
|
|
||
| Use American English spelling, such as “color” rather than “colour”. | ||
|
|
||
| Use lowercase for ordinary references to game content, such as “snow fox” rather than “Snow Fox”. Preserve capitalization when referring to code identifiers. |
There was a problem hiding this comment.
The developers do capitalise these words in official documents, such as in snapshot articles, so if you also want to stay consistent with Minecraft terminology these words should be capitalised imo
|
|
||
| ## Explain parameters and results only when needed | ||
|
|
||
| Use `@param`, `@return`, and `@throws` when they help the reader understand a parameter, result, or failure condition. Repeating information from the prose is fine when it makes the documentation clearer or easier to use. Parameter and return descriptions should be short phrases without an initial capital or final period. |
There was a problem hiding this comment.
I think it would be useful to require a specific tag order (this Oracle article is a useful reference) so all Javadocs stay consistently ordered. You could also disallow certain tags like @exception (as @throws is preferred) or @author.
|
|
||
| Inspired by [Yarn’s conventions](https://github.com/FabricMC/yarn/blob/1.21.11/CONVENTIONS.md) and [Effective Dart’s documentation guide](https://dart.dev/effective-dart/documentation). | ||
|
|
||
| For Markdown Javadoc syntax, see Oracle’s [Markdown in Documentation Comments](https://docs.oracle.com/en/java/javase/26/javadoc/using-markdown-documentation-comments.html) guide. |
There was a problem hiding this comment.
nit: use either the currently latest available Java version (27) or 25 as that's the current LTS and version Minecraft uses at the moment.
|
|
||
| ```markdown | ||
| @param namespace the namespace, restricted to `[a-z0-9_.-]` | ||
| ``` |
There was a problem hiding this comment.
Might be better to prefix these with the Javadoc comment so it's a little clearer:
/// @param namespace the namespace, restricted to `[a-z0-9_.-]`|
|
||
| ## Start with a short summary | ||
|
|
||
| Write a concise first sentence that makes sense on its own. Capitalize it and end it with a period. For methods, start with a verb such as “Returns”, “Sets”, or “Removes”. Add a blank line before further explanation. |
There was a problem hiding this comment.
I think the document should use ' and " instead of fancy quotes. This might also be a good thing to mention here so people use the correct ones in the Javadocs.
However, in lists like these I would recommend italic words instead of quotes so the sentences don't get cluttered with punctuation marks. On top of that, I would write the examples in lowercase despite being noted to be at the start of a sentence, as they are still part of this sentence.
| Write a concise first sentence that makes sense on its own. Capitalize it and end it with a period. For methods, start with a verb such as “Returns”, “Sets”, or “Removes”. Add a blank line before further explanation. | |
| Write a concise first sentence that makes sense on its own. Capitalize it and end it with a period. For methods, start with a verb such as *returns*, *sets*, or *removes*. Add a blank line before further explanation. |
|
|
||
| Use plain English and terminology consistent with Minecraft and nearby documentation. Describe behavior from the caller’s perspective rather than walking through the implementation. | ||
|
|
||
| Use American English spelling, such as “color” rather than “colour”. |
There was a problem hiding this comment.
Same formatting as mentioned earlier, italic words rather than quotes.
| Use American English spelling, such as “color” rather than “colour”. | |
| Use American English spelling, such as *color* rather than *colour*. |
|
|
||
| Write a concise first sentence that makes sense on its own. Capitalize it and end it with a period. For methods, start with a verb such as “Returns”, “Sets”, or “Removes”. Add a blank line before further explanation. | ||
|
|
||
| Use plain English and terminology consistent with Minecraft and nearby documentation. Describe behavior from the caller’s perspective rather than walking through the implementation. |
There was a problem hiding this comment.
Normal quotes instead of a fancy quotes as mentioned before.
| Use plain English and terminology consistent with Minecraft and nearby documentation. Describe behavior from the caller’s perspective rather than walking through the implementation. | |
| Use plain English and terminology consistent with Minecraft and nearby documentation. Describe behavior from the caller's perspective rather than walking through the implementation. |
|
|
||
| Use American English spelling, such as “color” rather than “colour”. | ||
|
|
||
| Use lowercase for ordinary references to game content, such as “snow fox” rather than “Snow Fox”. Preserve capitalization when referring to code identifiers. |
There was a problem hiding this comment.
Same formatting as mentioned earlier, italic words rather than quotes. (The other comment about the capitalisation still stands)
| Use lowercase for ordinary references to game content, such as “snow fox” rather than “Snow Fox”. Preserve capitalization when referring to code identifiers. | |
| Use lowercase for ordinary references to game content, such as *snow fox* rather than *Snow Fox*. Preserve capitalization when referring to code identifiers. |
| Inspired by [Yarn’s conventions](https://github.com/FabricMC/yarn/blob/1.21.11/CONVENTIONS.md) and [Effective Dart’s documentation guide](https://dart.dev/effective-dart/documentation). | ||
|
|
||
| For Markdown Javadoc syntax, see Oracle’s [Markdown in Documentation Comments](https://docs.oracle.com/en/java/javase/26/javadoc/using-markdown-documentation-comments.html) guide. |
There was a problem hiding this comment.
Normal quotes instead of a fancy quotes as mentioned before.
| Inspired by [Yarn’s conventions](https://github.com/FabricMC/yarn/blob/1.21.11/CONVENTIONS.md) and [Effective Dart’s documentation guide](https://dart.dev/effective-dart/documentation). | |
| For Markdown Javadoc syntax, see Oracle’s [Markdown in Documentation Comments](https://docs.oracle.com/en/java/javase/26/javadoc/using-markdown-documentation-comments.html) guide. | |
| Inspired by [Yarn's conventions](https://github.com/FabricMC/yarn/blob/1.21.11/CONVENTIONS.md) and [Effective Dart's documentation guide](https://dart.dev/effective-dart/documentation). | |
| For Markdown Javadoc syntax, see Oracle's [Markdown in Documentation Comments](https://docs.oracle.com/en/java/javase/26/javadoc/using-markdown-documentation-comments.html) guide. |
| Use [java.util.List#copyOf(java.util.Collection)] to create an unmodifiable copy. | ||
| ``` | ||
|
|
||
| Use `#` to reference a member of the current class, such as `[#clear()]`. Use `[clearing the entries][#clear()]` for a custom label in plain text, or a block tag such as `@see #clear()` for a related reference. Use ordinary Markdown links such as `[label](https://example.com)` for external URLs. |
There was a problem hiding this comment.
| Use `#` to reference a member of the current class, such as `[#clear()]`. Use `[clearing the entries][#clear()]` for a custom label in plain text, or a block tag such as `@see #clear()` for a related reference. Use ordinary Markdown links such as `[label](https://example.com)` for external URLs. | |
| Use `#` to reference a member of the current class, such as `[#clear()]`. Use `[clearing the entries][#clear()]` for a custom label in plain text, or a block tag such as `@see #clear()` for a related reference. Use ordinary Markdown links such as `[label](https://example.com)` for external URLs. |
|
Superseeded by: #7 |
Please provide feedback, even after this has merged this document is not set in stone