Java doc

Author: bowbahdoe

src/SUMMARY.md

@@ -890,16 +890,16 @@ Make them do one. -->
 
 # Sharing Code II
 
+<!-- 
+TODO: Wait for hermetic java
 - [Distribution](./distribution.md)
   - [jars](./distribution/jars.md)
-  - [jlink]()
+  - [jlink]() -->
 - [Documentation](./documentation.md)
   - [Documentation Comments](./documentation/documentation_comments.md)
-  - [javadoc]()
-  - [@param]()
-  - [@return]()
-  - [@throws]()
-  - [Markdown]()
+  - [Format](./documentation/format.md)
+  - [javadoc](./documentation/javadoc.md)
+  - [Challenges](./documentation/challenges.md)
 
 
 <!--- 

src/documentation/challenges.md

@@ -0,0 +1,24 @@
+# Challenges
+
+Remember the rules for this are
+
+- Try to use only the information given up to this point in this book.
+- Try not to give up until you've given it a solid attempt
+
+## Challenge 1.
+
+Run `javadoc` on some of your code. Add the command for doing so to a `Justfile`.
+Make sure to include cleaning stale of output.
+
+## Challenge 2.
+
+When you ran `javadoc` on your code you were almost certainly hit by a deluge of `warning: no comment`
+messages.
+
+Fix these by documenting that code enough that `javadoc` no longer gives you warnings.
+
+## Challenge 3.
+
+Read the [documentation for java.util.StringJoiner](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/StringJoiner.html).
+
+If you can, alter one of your projects to use it.

src/documentation/documentation_comments.md

@@ -9,9 +9,12 @@ You put these documentation comments above different elements of your program
 with text describing what the purpose of those elements are.
 
 ```java
-/// This class represents the i
+/// This class represents a ninja
 public class Ninja {
-
+    /// Says a catchphrase
+    public void forsooth() {
+        // ..
+    }
 }
 ```
 

src/documentation/format.md

@@ -0,0 +1,80 @@
+# Format
+
+```java,no_run
+import java.io.IOException;
+
+/// This class serves as a place to put examples
+/// of the different kinds of documentation as well
+/// as how to write documentation properly.
+///
+/// When specified after the three slashes
+/// you can write documentation using [Markdown](https://en.wikipedia.org/wiki/Markdown).
+///
+/// In Markdown you can just write text as you would in any file,
+/// line after line.
+///
+/// # For headings you can use a single hash
+///
+/// ## For subheadings you can use two
+///
+/// ### And so on
+///
+/// You can make unordered lists using hyphens
+///
+/// - A
+/// - B
+/// - C
+///
+/// And numbered lists like so
+///
+/// 1. One
+/// 2. Two
+/// 3. Thre
+///
+/// And so on. Definitely peruse up [tutorial on markdown](https://www.markdownguide.org/getting-started/)
+/// when you have the time.
+///
+/// There are some additions specific to Java though.
+/// We call these additions "tags."
+///
+/// One notable tag is the author tag. It lets you mark who worked
+/// on a given unit of code
+///
+/// @author Ethan McCue
+/// @see [https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html)
+public class DocumentationExample {
+    /// You can document the purpose of parameters
+    /// to constructors and methods with the param tag
+    ///
+    /// @param o Demonstrates a param tag on a constructor
+    public DocumentationExample(Object o) {
+
+    }
+
+    /// Generic parameters can also be documented using the param tag
+    /// as well.
+    ///
+    /// @param item The item to just return back
+    /// @param <T> The type of the item.
+    public static <T> T identity(T item) {
+        return item;
+    }
+
+    /// The exceptions thrown by a method can also be documented
+    ///  to explain under what conditions the exceptions might be thrown
+    ///
+    /// @param s A parameter to show that throws can be used alongside params
+    /// @throws IOException whenever the method is called, no matter what
+    public void crash(String s) throws IOException {
+        throw new IOException();
+    }
+
+    /// You can reference other classes and methods on those classes with the
+    /// link tag.
+    ///
+    /// For instance {@link String} and {@link String#length()}.
+    public void seeMore() {
+
+    }
+}
+```

src/documentation/javadoc.md

@@ -0,0 +1,22 @@
+# javadoc
+
+The way to take code with documentation comments and produce a documentation website
+is with the `javadoc` tool.
+
+There are multiple ways to run this[^theme], but if you have your code in the
+multi-module directory layout you can use `--module-path` and `--module` the
+same as `javac` does.
+
+```bash,no_run
+javadoc \
+    -d output/javadoc \
+    --module-source-path "./*/src" \
+    --module one.piece
+```
+
+This will produce a directory full of HTML files that contain all
+the documentation from the specified modules.
+
+This is what is used to make [the official Java documenation](https://docs.oracle.com/en/java/javase/24/docs/api/index.html) as well as at least part of the documentation for most Java libraries.
+
+[^theme]: As is a theme with command-line tools