Conventions based on #5

.gitignore

@@ -18,4 +18,5 @@
 !gradlew.bat
 !LICENSE
 !README.md
+!CONVENTIONS.md
 !settings.gradle

CONVENTIONS.md

@@ -0,0 +1,98 @@
+# JavaDoc conventions
+
+## Follow grammar conventions
+
+Use American English spelling.
+
+Use terminology consistent with Minecraft and nearby documentation.
+
+Preserve capitalization and spelling when referring to code.
+
+```diff
+// In this example, "fops" is not American English, the terminology "attacking something" is non-standard, and the terminology "leap" doesn't match the method name ("jump").
+-/// leap over nearby fops when not attacking something
+public void jumpOverFoxes() { /*...*/ }
+
+// Uses proper capitalization and punctuation, terminology consistent with other documentation, and American English.
++/// Jump over nearby foxes as long as `this` is not aggressive.
+public void jumpOverFoxes() { /*...*/ }
+```
+
+## Add value
+
+Explain only what a developer cannot learn from the member's declaration. Leave obvious members undocumented.
+
+Document only what a caller needs to know. Don't walk through implementation.
+
+```diff
+// All this info is already in the method name.
+-/// Gets the width.
+public double getWidth() { /*...*/ }
+
+// Specifies the otherwise unknown unit.
++/// Returns the width in pixels.
+public double getWidth() { /*...*/ }
+
+// All this info is already in the method name. There's not anything else to add.
+-/// Returns the id of this object.
+public Identifier getId() { /*...*/ }
+```
+
+## Start with a summary
+
+Write a concise first sentence that can stand alone. For methods, start with a verb such as "Returns," "Sets," or "Removes." Add a blank line before further explanation (if any is required).
+
+```diff
+// A short and glanceable summary is added.
++/// Iterates over a column of blocks, then over all its neighbor columns.
++/// 
+/// Iterates from `(startX, startY, startZ)` until `y==endY` (exclusive), then does the same for each of the columns on the north, east, south, and west of the first column. Iterates upwards if `startY<endY`, downwards if `startY>endY`.
+public static Iterable<BlockPos> neighborColumn(int startX, int startY, int startZ, int endY) { /*...*/ }
+```
+
+## Use Markdown format
+
+Use backticks (\`) for identifiers, literals, and short expressions. Separate paragraphs with blank lines. Prefer Markdown lists and fenced code blocks over HTML. Use markdown links instead of `{@link}` or `{@linkplain}`.
+
+When linking to a member of the same class, use `#` (such as `[#clear()]`).
+
+For syntax reference, see [Oracle's JavaDoc Guide](https://docs.oracle.com/en/java/javase/25/javadoc/using-markdown-documentation-comments.html).
+
+```diff
+// Uses the old style of comment, and HTML link, {@code} instead of backticks, and a qualified link to a member of the same class (ThisClass).
+-/**
+- * Returns a random integer generated by <a href="https://github.com/FabricMC/community/blob/main/images/tinypotatoinafield.png" Tiny Potato>. {@code 4} is weighted more heavily than any other number.
+- * 
+- * Also see {@link ThisClass#veryBadNumber()}.
+-**/
+public static int veryGoodNumber() { /*...*/ }
+
+// Uses a markdown-style comment. The link format is correct. It uses backticks for the constant "4" and omits "ThisClass" from "ThisClass#veryBadNumber".
++/// Returns a random integer generated by [Tiny Potato](https://github.com/FabricMC/community/blob/main/images/tinypotatoinafield.png). `4` is weighted more heavily than any other number.
++/// 
++/// @see #veryBadNumber()
+public static int veryGoodNumber() { /*...*/ }
+```
+
+## Explain parameters and return values only when needed
+
+Use `@param`, `@return`, and `@throws` when they help the reader better understand a method's usage. Information may be repeated from the rest of the JavaDoc. **Use short phrases without an inital capital or final period.**
+
+Document only the parameters of a method that need explanation. A method may have both documented and undocumented parameters.
+
+Take special care to document special parameter cases (such as using `-1` to indicate no limit). 
+
+Use `@throws` to explain a relevant failure condition, not to list every exception that could be produced.
+
+```diff
+// Explains extra parameter restrictions.
++/// ...
++/// @param namespace the namespace, restricted to `[a-z0-9_.-]`
+public static Identifier fromNamespaceAndPath(String namespace, String path) {/*...*/}
+
+// Explains units and a special case.
++/// ...
++/// @param timeout the maximum wait in milliseconds, or `-1` to wait indefinitely
+public void waitForEndUpdate(long timeout) {/*...*/}
+```
+