CommandAPI JavaDocs

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

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 e6f77968b97133d3739936abdd90fa58e1530b4e.

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 a JorelAli/brigadier-with-javadocs.

Building the JavaDocs

• If necessary, edit the global Doxyfile to have the correct paths. There are some directories which don't have generated documentation (primarily the NMS ones) which are specified in EXCLUDE.

• Get JorelAli's fork of Brigadier:

  • Clone the fork with the following command:

    git clone https://github.com/JorelAli/brigadier-with-javadocs

  • Ensure the directory is in the right place relative to the CommandAPI project (See Doxyfile INPUT value, by default we assume it's in the directory above the CommandAPI's main directory):

    .
    ├── CommandAPI
    │   └── ...
    └── brigadier-with-javadocs
        └── ...
    

• Run Doxygen (e.g. via the graphical Doxywizard application, or otherwise). To use the graphical Doxywizard application (this is what I use):

  • Download Doxygen from the Doxygen: Downloads page. On Windows, this is under "A binary distribution for Windows. All 64bit versions of Windows are supported". For other operating systems, they'll be under "Sources and Binaries"

  • Run Doxygen's GUI (Doxywizard), then go to File > Open... and open the Doxyfile in the root of the CommandAPI repo

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

  • Press the Run doxygen button: