mirror of https://github.com/FabricMC/yarn.git
More comprehensive javadoc conventions (#2051)
* Squashed commit of the following: commit b66d5953cdd5a671af8aa93b05c63584d7d5ffec Merge: a517a6fab47f65f51654Author: liach <7806504+liach@users.noreply.github.com> Date: Thu Apr 22 10:55:59 2021 +0700 Merge branch '21w16a' into 21w06a-2 commit a517a6fab4a648153d2af91cccf165618fb4cdeb Merge: ae8afb008e232a1e0b9fAuthor: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu Apr 8 00:07:28 2021 +0000 Merge branch '21w14a' into 21w06a-2 commit ae8afb008e0edfb005f8fc4d0ef65fc601c82ab7 Merge: ee10f51f18e15349595dAuthor: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed Mar 31 23:35:18 2021 +0000 Merge branch '21w13a' into 21w06a-2 commit ee10f51f189cac5f6aa59fb000ada2a989fcf14b Merge: 0218c2a387bf4d6850bdAuthor: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu Mar 18 02:29:22 2021 +0000 Merge branch '21w11a' into 21w06a-2 commit 0218c2a387a8cca390743a04974db257bcd5e5f8 Merge: 45ca6452b4252ad11d0aAuthor: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed Mar 10 19:32:17 2021 +0000 Merge branch '21w10a' into 21w06a-2 commit 45ca6452b4d329eed9cdefd1737f22e15e175616 Author: liach <7806504+liach@users.noreply.github.com> Date: Mon Feb 22 07:07:17 2021 -0600 Update CONVENTIONS.md Co-authored-by: haykam821 <24855774+haykam821@users.noreply.github.com> commit e99c08f313cf21d9cd4076acb9b889126214e031 Author: liach <liach@users.noreply.github.com> Date: Sun Feb 21 19:19:19 2021 -0600 Address player's concerns Signed-off-by: liach <liach@users.noreply.github.com> commit 112ad37d74efb585eaf212a820a527608acdfe06 Author: liach <7806504+liach@users.noreply.github.com> Date: Mon Feb 15 22:40:31 2021 -0600 Update CONVENTIONS.md commit d029970d8be3aa49aa52d05618cae01c50ac7eb6 Author: liach <liach@users.noreply.github.com> Date: Mon Feb 15 18:08:55 2021 -0600 Fixes a few problems from haykam's suggestions Signed-off-by: liach <liach@users.noreply.github.com> commit 30930a7298832090a3c06581631d4f453a8632f1 Author: liach <7806504+liach@users.noreply.github.com> Date: Mon Feb 15 17:45:26 2021 -0600 Apply suggestions from code review Still needs furnishing Co-authored-by: haykam821 <24855774+haykam821@users.noreply.github.com> commit b06652dc3f0b22876907a5e4457fdd1f42cc79fe Author: liach <7806504+liach@users.noreply.github.com> Date: Fri Feb 12 16:39:37 2021 -0600 Update CONVENTIONS.md Co-authored-by: enbrain <69905075+enbrain@users.noreply.github.com> commit 8cb65e7a0d36cf4633501ff526eaccdbc60969fd Author: liach <liach@users.noreply.github.com> Date: Fri Feb 12 15:18:42 2021 -0600 More comprehensive javadoc conventions Signed-off-by: liach <liach@users.noreply.github.com> * Modernize information and my notes Signed-off-by: liach <liach@users.noreply.github.com> * Update CONVENTIONS.md Co-authored-by: enbrain <69905075+enbrain@users.noreply.github.com> Co-authored-by: liach <liach@users.noreply.github.com> Co-authored-by: enbrain <69905075+enbrain@users.noreply.github.com>
This commit is contained in:
liach
GitHub
parent
f79141cc44
commit
0d0a71ba96
|
|
@ -117,12 +117,93 @@ Name screen coordinates `x` and `y`, rather than `left` and `top`.
|
|||
|
||||
## Javadocs
|
||||
|
||||
Write sentences for class, method and fields javadocs, starting with an uppercase and ending with a period. Start method docs with verbs, like `Gets` or `Called`. Use HTML tags such as `<p>` if the docs have several paragraphs.
|
||||
Write sentences for class, method and fields javadocs, starting with an uppercase and ending with a period. Start method docs with verbs, like `Gets` or `Called`. Use HTML tags such as `<p>` if the docs have several paragraphs, as line wraps are converted to spaces in the generated documentation. Feel free to start a new line whenever you feel the current line is too long.
|
||||
|
||||
Write quick descriptions for parameter javadocs as well as `@return` tags, with no uppercase or period. Add parameter docs to the parameter itself instead of using the `@param` tag.
|
||||
Parameter and `@return` documentation should use quick descriptions without initial capitalization or punctuation, such as `{@code true} if the block placement was successful, {@code false} otherwise`. `{@return}` used in first sentence can duplicate enclosed text to the return description.
|
||||
|
||||
Use `{@index}` to allow enclosed text to be indexed by the Javadoc search.
|
||||
|
||||
Avoid using the `@param` tag for documentation of methods. Add parameter documentations to the parameter itself instead of adding `@param` tags to its owner method, so Matcher can update them properly across Minecraft updates. However, you can use the tag for type parameters (such as `<T>` in `public class Lazy<T>`), which cannot be documented separately.
|
||||
|
||||
Javadoc will take the first sentence, ended by the first `.`, as a brief description of the member you are documenting. Note that `.` from abbreviations, such as `i.e.`, count.
|
||||
|
||||
### Packages
|
||||
|
||||
Since enigma format does not support `package-info.java` file creation, yarn keeps these files in `src/packageDocs/java` to supply javadocs for packages. Their only purpose is to host Javadoc for yarn packages, which are currently not exported to mappings, and their Javadocs should follow the conventions just like enigma-based Javadocs.
|
||||
|
||||
### Tooling
|
||||
|
||||
Fabric-hosted Javadocs are generated using [JDK 16 Standard Doclet](https://docs.oracle.com/en/java/javase/16/docs/specs/javadoc/doc-comment-spec.html) and can use any feature it supports. For example, it has a [list of supported tags](https://docs.oracle.com/en/java/javase/16/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used). You can personally build the documentation with a newer Java version. See [the 'Checking Javadoc' section](#checking-javadoc) for how to build the documentation locally.
|
||||
|
||||
### Custom tags
|
||||
|
||||
A few additional block tags are supported:
|
||||
|
||||
- `@apiNote`: API Notes. A few comments for users of the documented API.
|
||||
- `@implSpec`: Implementation Specification. Tells how this method is implemented; usually avoided as yarn doesn't define implementations.
|
||||
- `@implNote`: Implementation Notes. A few comments on the implementation.
|
||||
|
||||
Feel free to use these tags and write under these sections.
|
||||
|
||||
### Linking to other members
|
||||
|
||||
Use `@link`, `@linkplain` and `@see` tags to refer to other parts of the code.
|
||||
|
||||
You can use the simple name of a class when its import is assumed to exist.
|
||||
|
||||
A class is assumed to be imported in the following scenarios:
|
||||
|
||||
- If it is from the `java.lang` package
|
||||
- If it is from the same package as the currently documented class
|
||||
- If it is used as part of its API, such as in the signature of the class or its members (methods and fields). See Javadoc's definition of "use" in its [`-use` command line option specification](https://docs.oracle.com/en/java/javase/16/docs/specs/man/javadoc.html#options-for-javadoc).
|
||||
|
||||
If it does not fulfill one of these scenarios, use the [full binary name](https://docs.oracle.com/en/java/javase/16/docs/api/java.base/java/lang/ClassLoader.html#binary-name), such as `com.google.common.collect.Lists` rather than simply `Lists`. Unlike class naming in enigma, do not use `/` to separate packages; use `.` instead.
|
||||
|
||||
Use Yarn mappings when referencing Minecraft members, such as `net.minecraft.server.world.ThreadedAnvilChunkStorage` rather than `net.minecraft.class_3898`. The Javadoc task will warn if some links no longer work after a rename.
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
An example
|
||||
</summary>
|
||||
|
||||
Assume this is the decompiled content in Enigma, which does not show imports:
|
||||
|
||||
```java
|
||||
/**
|
||||
* Assume this class is from the {@code net.example.stuff} package.
|
||||
*
|
||||
* <p>You can link to {@link Optional} as it's part of the class signature (type parameter bound).
|
||||
*
|
||||
* <p>You must fully qualify {@link net.example.stuff.basic.BasicStuffUser} when linking as it is not in
|
||||
* any signature and is from a different package.
|
||||
*/
|
||||
public class Stuff<T extends Optional<?>> {
|
||||
/**
|
||||
* You can link to {@link Listener} with the simple name as it's part of a field's signature.
|
||||
*/
|
||||
protected Listener listener;
|
||||
|
||||
/**
|
||||
* You can link to {@link List} with the simple name as it's part of a method's signature.
|
||||
*
|
||||
* <p>You must fully qualify {@link net.example.util.UtilityClass} when linking because it is not part
|
||||
* of any signature (even though it is used in code) and is from a different package.
|
||||
*/
|
||||
public Stuff(List<Integer> opt) {
|
||||
UtilityClass.callMethod(opt);
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
### Checking Javadoc
|
||||
|
||||
After writing a Javadoc, you should check its validity. This can easily be done from GitHub using the 'Checks' section, or by clicking the check icon after each commit. For any JDK version, the section titled `Run ./gradlew build javadocJar checkMappings mapNamedJar --stacktrace` will contain output related to Javadoc generation in the `Task :javadoc` section.
|
||||
|
||||
You can also check Javadoc validity locally using the `./gradlew javadoc` (Linux, macOS) or `gradlew javadoc` (Windows) commands; this will take a while given the sheer size of the Minecraft codebase. After that, you can enter the `build/docs/javadoc` directory to obtain the generated Javadoc and ensure it renders correctly.
|
||||
|
||||
If you are unsure if your Javadoc is correct stylistically, we recommend you to run the `javadoc` task and check its output, as described in the previous paragraph.
|
||||
|
||||
### Game content capitalization
|
||||
|
||||
When describing content in the game itself, do not use capitalization. For example, the following is incorrect:
|
||||
|
|
|
|||
Loading…
Reference in New Issue