Skip to content

Latest commit

 

History

History
97 lines (62 loc) · 4.97 KB

README.md

File metadata and controls

97 lines (62 loc) · 4.97 KB

Generate Documentation with javadoc

Project Structure

Here's a breakdown of the different project components:

  • src/main/java: The source code for the project, organized by package:
    • eu.ammbra.bday.Organizer.java: The main entry point of the application, possibly responsible for coordinating the overall flow of the program.
    • eu.ammbra.bday.details: A package containing domain model classes. These classes represent entities involved in birthday celebrations, such as cakes, parties, and people attending them.
    • eu.ammbra.bday.handlers: A package containing classes responsible for handling specific tasks.
    • eu.ammbra.bday.operations: A package containing classes responsible for handling the operational side of parties.
    • eu.ammbra.bday.store: A package containing classes responsible for interacting with data from files.
  • src/main/resources/store/events.json: A resource file containing sample event data in JSON format.
  • src/test/java: The source code for unit tests and integration tests.
  • src/snippets: The JSON snippets folder.

Lab Activity No 1: Introduce a Code Snippet in JavaDoc Comments

Since JDK 18 you can simplify the way you add code examples in API documentation by utilizing snippets. You can use {@snippet ...} to enclose a fragment of text, such as source code or any other form of structured text.

/**
 * {@snippet :
 *   public static void main(String... args) {    // @highlight region substring="text" type=highlighted
 *      var text = "";                            // @replace substring='""' replacement=" ... "
 *      System.out.println(text);
 *   }                                            // @end
 * }
 */

To highlight all or part of a line in a snippet, use the @highlight tag. In the example above, the empty string is used as a placeholder value, and the @replace tag specifies that it should be replaced with an ellipsis.

The markup comments in the previous example only affected the content on the same line. However, sometimes you may want tot affect the content on a range of lines, or region. Regions can be anonymous or named. To have a markup tag apply to an anonymous region, place it at the start of the region and use an @end tag to mark the end of the region.

Your task relies on you to do the following steps:

  1. Add a snippet tag on the loadJson method from lab-jdk-tools/B_bday_javadoc/src/main/java/eu/ammbra/bday/store/JsonLoader.java file.
  2. This snippet tag should contain the json from lab-jdk-tools/B_bday_javadoc/src/snippets/sample.json.
  3. Optionally, you can try to add a region to highlight parts of the JSON.

To validate your work, run javadoc command in a terminal window:

# Unix and macOS compatible command

javadoc -cp "../lib/*" -d docs -sourcepath src/main/java -subpackages eu.ammbra.bday.store eu.ammbra.bday

# Windows compatible command

javadoc -cp "..\lib\*" -d docs -sourcepath src\main\java -subpackages eu.ammbra.bday.store eu.ammbra.bday

Now go to docs folder and inspect the generated documentation.

Solution

→ Click to see the solution

Lab Activity No 2: Reference the Code Snippet from a File

It is not always convenient to use inline snippets. Moreover, the Standard Doclet does not compile or otherwise test snippets; instead, it supports the ability of external tools and library code to test them.

Your task relies on you to do the following steps:

  1. Modify the snippet tag on the loadJson method to load the json content from src/snippets/sample.json.
  2. Modify the previous javadoc command to reference external snippets (--snippet-path src/snippets).
  3. Run javadoc in a terminal window.
  4. Now go to docs folder and inspect the generated documentation.
  5. Modify testLoadJson_ValidFile method from JsonLoaderTest.java to test the content from src/snippets/sample.json.

Solution

→ Click to see the solution

Lab Activity No 3: Utilize Markdown in JavaDoc Comments

As of JDK 23, you can use Markdown in Javadoc comments.

This activity relies on you to execute the following steps:

  1. Go to the src/main/java/eu/ammbra/bday/store/JsonLoader.java file.
  2. Change its JavaDoc comments to use Markdown.
  3. Check if the previous javadoc command still works. If it doesn't work, find the appropriate option to fix it.
  4. Go to docs folder and inspect the generated documentation.

Solution

→ Click to see the solution

Next, let's create a simple client-server setup!