CommandAPI Javadocs

The CommandAPI JavaDocs are manually generated using Doxygen. Doxygen is a documentation generator for C++, which also has some support for Java and a cleaner, more modern interface with support for inheritance diagrams (amongst other features). Doxygen can be downloaded here.

Building the JavaDocs

• If necessary, download and install Doxygen as detailed in their documentation here.

• Update the git submodules CommandAPI and brigadier-with-javadocs to point to the version you want to generate javadocs for. Typically, this will be the latest commit on the respective master branches. The submodules should already be on the master branch with no local changes, in which case you can simply run git pull for each submodule:

cd CommandAPI
git pull
cd ..

cd brigadier-with-javadocs
git pull
cd ..

• If necessary, update the PROJECT_NUMBER tag in the Doxyfile to the appropriate CommandAPI version.

• Run Doxygen via the terminal or graphical Doxywizard application. For the CLI, simply run doxygen in the root of this repository. For the GUI:

  • Go to File > Open... and open the Doxyfile in the root of this repository

  • Go to the Run tab (next to Wizard and Expert)

  • Press the Run doxygen button:

    

Why Doxygen instead of JavaDocs?

I chose to use Doxygen over JavaDocs because Bukkit's original JavaDocs were also generated using Doxygen and I preferred the UI to the standard JavaDocs UI. Additionally:

• Doxygen has inheritance diagrams:

  

• Doxygen shows the JavaDocs for inherited methods without requiring you to navigate to the relevant inherited class/interface to view its method descriptions:

  

• Doxygen makes it easy to pull in other projects into the documentation:

  

Known issues

Java classes with generics that extend other classes aren't properly generated in Doxygen. For example:

public class MyClass<T extends List<String>> {
  public String someField;
}

This is currently a known issue on Dogyxen (see here) and development was done to rectify this (see here), but at the time of writing (Feb 2023) no further progress has been done on this issue.

This issue can be circumvented using Doxygen's \cond preprocessor command. By applying a @cond comment followed by a label, then a subsequent @endcond comment around generics, this issue can be avoided. An example of this can be found in the CommandAPI repository at this commit.

For example, if you take this class parameterized with generics T and U, and the U generic extends another class, this will cause Doxygen to skip all methods declared in MyClass:

public class MyClass<T, U extends SomeOtherClass<T>> {
  ...
}

You can fix this by adding the relevant \cond guards. By default, the CommandAPI uses the label DOX:

public class MyClass<T, U
/// @cond DOX
extends SomeOtherClass<T>
/// @endcond
> {
  ...
}

Brigadier JavaDocs

As the CommandAPI heavily depends on Mojang/brigadier, the CommandAPI's JavaDocs also includes Brigadier's JavaDocs. JavaDocs for Brigadier were kindly written by I-Al-Istannen because the main Brigadier repository doesn't have any of their own JavaDocs.

JorelAli currently hosts a fork of Mojang/brigadier which is up-to-date, and incorporates the changes from I-Al-Istannen/brigadier which is compatible with Doxygen (it has the @cond DOX guards). The fork can be found at CommandAPI/brigadier-with-javadocs, and is included as a submodule of this repository.