https://github.com/commandapi/javadocs
https://github.com/commandapi/javadocs
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/commandapi/javadocs
- Owner: CommandAPI
- License: mit
- Created: 2024-12-10T00:44:08.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-02T22:13:14.000Z (10 months ago)
- Last Synced: 2025-06-02T06:08:06.173Z (8 months ago)
- Language: CSS
- Homepage: http://javadocs.commandapi.dev/
- Size: 4.89 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://www.doxygen.nl/download.html#srcbin).
## Building the JavaDocs
- If necessary, download and install Doxygen as detailed in their documentation [here](https://www.doxygen.nl/manual/install.html).
- 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:
```shell
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:
```java
public class MyClass> {
public String someField;
}
```
This is currently a known issue on Dogyxen (see [here](https://github.com/doxygen/doxygen/issues/8495)) and development was done to rectify this (see [here](https://github.com/doxygen/doxygen/pull/8534)), 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](https://www.doxygen.nl/manual/commands.html#cmdcond). 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](https://github.com/CommandAPI/CommandAPI/commit/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`:
```java
public class MyClass> {
...
}
```
You can fix this by adding the relevant `\cond` guards. By default, the CommandAPI uses the label `DOX`:
```java
public class MyClass
/// @endcond
> {
...
}
```
## Brigadier JavaDocs
As the CommandAPI heavily depends on [Mojang/brigadier](https://github.com/Mojang/brigadier), the CommandAPI's JavaDocs also includes Brigadier's JavaDocs. JavaDocs for Brigadier were kindly written by [I-Al-Istannen](https://github.com/I-Al-Istannen) because the main Brigadier repository doesn't have any of their own JavaDocs.
JorelAli currently hosts a fork of [Mojang/brigadier](https://github.com/Mojang/brigadier) which is up-to-date, and incorporates the changes from [I-Al-Istannen/brigadier](https://github.com/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](https://github.com/CommandAPI/brigadier-with-javadocs), and is included as a submodule of this repository.