This project is an extension of the Living Documentation set of tools to Java. As part of the Living Documentation toolchain, it can be used to generate documentation and diagrams from source code so that documentation is always up-to-date.
As of February 2024, this project is linked to a student assignment originating from the University of Twente and Info Support. The aim of the project is to make the Living Documentation project capable to handle multilingual projects. One aspect of this is to make Living Documentation available for the Java environment; which is the purpose of this repository.
This includes:
- Java Analyzer
- Maven and Gradle plugin to execute the analyzer
- A general support library (the project reader)
- Sample renderers illustrating how Living Documentation can be used
Note: at the moment of writing (February 2024), the student project is coming to an end. It is expected that the repository will be moved at some time. When this happens, this repository will refer to the new one.
The process of rendering documentation can be summarized as follows:
- Analysis: Run the Analyzer over the source code of your project. This creates a Living Documentation JSON file.
- Install the analyzer as a maven plugin (see maven plugin)
- Include the maven plugin in your project (see ldj-maven-plugin-example for an example)
- Either rebuild your project in case you added the action to your build pipe, or call the plugin manually (through
mvn ldj:livingdocumentation)
- Render the documentation: Use a (custom) renderer that reads the generated JSON file and outputs documentation
Renderers are applications that you can write yourself making use of the support Libraries. These interpret the analyzed code and create documentation files.
JSON format documentation describing the structure of the JSON file, as well as a description in JSON Schema format, are available as part of this repository.
Next to these, sample applications along with a renderer are available (see sample applications renderers)
The analyzer takes Java source code as input and generates a JSON file (containing a representation of the AbstractSyntaxTree which is compatible with other Living Documentation applications).
It can be used either as a Java command line application or as a Maven plugin.
The Java analyzer can be invoked directly as a plain Java application analyzer-java. It accepts the following command line options:
| Short option | Long option | Description |
|---|---|---|
--output |
The file path to save the output JSON to. (Required.) | |
--project |
Root directory of the project to analyze. (Required.) | |
-p |
--pretty |
Indent (pretty-print) JSON output. |
--classpath |
(Semi)colon-separated list of JAR paths to use during type resolution. |
The analyzer can also be used as a Maven plugin (which is defined in ldj-maven-plugin).
For an example on how to use the Maven plugin, see the pom.xml configuration in ldj-maven-plugin-example.
Note: As of right now (February 2024), the Maven plugin is not published to a public Maven repository. If one would like to use the analyzer in the form of a plugin, one can manually install the plugin using Maven install. After a manual install, the plugin can be used as defined in the ldj-maven-plugin-example.
A list of Java language features which are included in the analyzer can be found in the JSON format documentation.
This repository contains the Project Reader, which is a support library that eases the creation of renderers. This is done by providing a Java interface to deserialize the Living Documentation JSON file.
This repository contains two sample applications that make use of the Java Spring framework (Spring events & Spring AMQP). For both these sample applications a renderer has been made (which generates a UML sequence diagram). This may serve as a source of inspiration for creating your own renderers.
At the moment, this repository is associated to a student assignment of the University of Twente. Due to grading criteria, it may not be possible to contribute to this project.
- Did you find a bug? Please report this, this will help improve the project and does not collide with the educational guidelines.
- In the case you want to add a new feature, please contact one of the authors. Depending on the feature, it may or may not be possible to implement this yourself.
The university assignment is expected to end around February 2024. From that moment, the repository is expected to be moved. This page will provide an update in case that happens.