A tool for generating UML diagrams and markdown documentation indexes.
The palest ink is better than the best memory.
— Chinese proverb
Lexakai - from lexis (greek for word) and kai (hawaiian for ocean).
Lexakai creates documentation indexes and UML diagrams from the source code of each maven or gradle project discovered recursively from the root folder(s) given as argument(s).
| Resource | Description |
|---|---|
| Project Name | Lexakai |
| Summary | Lexakai creates markdown and UML from Java source code |
| Javadoc Coverage |  |
| Lead | Jonathan Locke (Luo, Shibo) jonathanl@telenav.com |
| Administrator | Jonathan Locke (Luo, Shibo) jonathanl@telenav.com |
| kivakit@telenav.com | |
| Chat | Zulip |
| @OpenLexakai | |
| Issues | GitHub Issues |
| Code | GitHub |
| Checkout | git clone https://github.com/Telenav/lexakai.git |
-
Install GraphViz for generating SVG files
-
Download Lexakai
-
Run Lexakai with java -jar
Examples of Lexakai documentation:
Lexakai automatically creates basic package diagrams for all public types without further configuration.
To create a set of one or more custom diagrams for a project, annotations can be used from this project:
<dependency>
<groupId>com.telenav.lexakai</groupId>
<artifactId>lexakai-annotations</artifactId>
<version>0.9.3</version>
</dependency>
A class, annotation, enum or interface annotated with @UmlClassDiagram(diagram = [marker-interface].class), where [marker-interface] extends the interface UmlDiagramIdentifier, will be included in the specified diagram.
For example, a type annotated with:
@UmlClassDiagram(diagram = DiagramMapServer.class)
will be included in the diagram diagram-map-server (the lowercase, hyphenated name derived from the marker interface name). A type can be used in more than one diagram, by specifying more than one @UmlClassDiagram annotation:
@UmlClassDiagram(diagram = DiagramMapServer.class)
@UmlClassDiagram(diagram = DiagramServers.class)
The preferred location for diagram marker interfaces is in the sub-package project.lexakai, and they should be prefixed with * Diagram* to make their use clear.
Groups of methods can be specified using the @UmlMethodGroup annotation. Method groups will be given labeled separators in class diagrams, making the list of methods easier to understand.
For example:
@UmlMethodGroup("settings")
could be used to label all the settings-related methods in a type. Multiple @UmlMethodGroup annotations can be added to specify that a method should be shown in more than one group.
The @UmlMethodGroup annotation can be avoided if the switch -automatic-method-groups is set to true (which is the default). In this case, the best guess will be made based on method name and parameter patterns as to which group a method most likely belongs. When the guess is inaccurate, or no guess is made, an @UmlMethodGroup annotation can be applied to correct the result. The set of patterns that are used to determine automatic groups is in a file called lexakai.groups in the Lexakai settings folder. This file can be customized for a particular project. An explicit annotation can be used to override any automatic group assignment(s) for a method.
Patterns in the names of types, fields and methods are used to try to deduce UML associations. The annotation @UmlRelation can be used to override this guess with an explicit relation if the association was not be deduced, or it was deduced incorrectly.
If the annotation @UmlRelation(label = "label") is applied to a method or field, a relation arrow will be drawn from the enclosing type to the type of the member. Similar annotations are available for field aggregation (@UmlAggregation) and composition (* @UmlComposition*). If the @UmlRelation tag is applied to a type, it can specify a relation with a particular referent and cardinality. An explicit relation of this type can be made specific to a particular diagram with the diagram parameter. Multiple @UmlRelation tags can be applied to a type.
Methods and fields can be excluded entirely by labeling them with @UmlExcludeMember.
@UmlNotPublicApi marks a type or member as private even if it is not actually private.
- @UmlClassDiagram - declares the diagram(s) that the annotated type should be included in
- @UmlMethodGroup - includes the annotated method in a labeled method group in the diagram
- @UmlNote - adds a callout note to a type or method
- @UmlExcludeSuperTypes - excludes the listed supertypes from all diagrams
- @UmlExcludeMember - excludes the annotated member
- @UmlIncludeMember - includes the annotated member, even if it wouldn't normally be included
- @UmlNotPublicApi - marks the annotated type or member as private even if it is not
- @UmlRelation - adds a labeled UML relation from the enclosing type to the annotated member type
- @UmlAggregation - adds a UML aggregation association from the enclosing type to the annotated field type
- @UmlComposition - adds a UML composition association from the enclosing type to the annotated field type
Each root project that Lexakai processes must have a documentation/lexakai folder. This folder must contain all the settings that Lexakai uses to create documentation. When Lexakai is run for the first time, this folder will be created and populated with default settings files. Settings for individual projects can then be added to the projects subfolder, so the final tree looks like this:
+ documentation
\---+ lexakai
| lexakai.settings
| lexakai.theme
| lexakai.groups
| lexakai-source-readme-template.md
| lexakai-project-readme-template.md
\---+ projects
my-project.properties
my-project-sub-project.properties
where these files are described as follows:
| Settings File | Description |
|---|---|
| lexakai.settings | Global settings for all projects under the root folder |
| lexakai.theme | PlantUML theme file copied to each diagram output folder |
| lexakai.groups | Patterns used to automatically group methods |
| lexakai-source-readme-template.md | README.md template for projects that have source code |
| lexakai-project-readme-template.md | README.md template for projects that have child projects |
| projects/[project].properties | Markdown and UML settings for each project in the source tree |
The .theme, .groups and README.md template files can be customized. To perform a 'factory-reset' on these resources, run Lexakai with -overwrite-resources=true or simply remove the files and Lexakai will re-create them. The [project] value in the table above should be the hyphenated artifact id for the project, as defined in pom.xml, such as kivakit-core-kernel.
This global settings file contains the following properties:
#
# Locations of resources linked to from README.md files
#
lexakai-documentation-location = https://www.lexakai.org/lexakai
lexakai-javadoc-location = https://www.lexakai.org/javadoc
lexakai-images-location = https://telenav.github.io/images
project-footer = <sub>Copyright © 2011-2021, Me</sub>
These values specify the location of resources for Lexakai when it is producing links in README.md files. When using GitHub Pages, the folders lexakai, javadoc and images are normally in the docs folder in a documentation project and GitHub Pages is configured to share that folder with the world.
Each project in the source tree requires a [project].properties file in the projects folder, which looks like:
#
# Project
#
project-title = kivakit-core-network-core
project-description = This module provides core networking functionality.
project-icon = nucleus-32
#
# Diagrams
#
diagram-port = Hosts, Ports and Protocols
diagram-network-location = Network Locations
The project-title, project-description and project-icon values will be used to populate values in the README.md templates (described above). The project-icon value is used as the base name of [project-icon].png and [project-icon]-2x.png, in order to support HiDPI displays. The diagrams section provides titles for individual UML diagrams. The lowercase, hyphenated name of the marker interface (as described above) is used as a key to locate the title of the diagram. For example:
@UmlClassDiagram(diagram = DiagramMyUtilities.class)
refers to the diagram title specified by the key diagram-my-utilities in the .properties file for the project.
If the -update-readme switch is set to true (it is false by default to ensure it doesn't overwrite an existing file), then a README.md file will be generated or updated each time the UML diagrams are generated. This markdown file will use project-title as its title and insert the description project-description from the [project].properties file as the project description.
An index of project diagrams is updated along with an index of the Javadoc (which should be available at lexakai-javadoc-location) for all types. Sections of documentation in the Javadoc can also be indexed based on the pattern specified by the switch -javadoc-section-pattern. By default, this pattern is:
<p><b>section-title</b></p>
which is the style used in KivaKit, but any regular expression pattern can be substituted.
Any text between the markdown comments start-user-text and end-user-text will be preserved, allowing additional documentation to be maintained.
The first run of Lexakai on a project will create two default templates in the documentation/lexakai settings folder one for projects with source code and one for parent projects (projects with sub-projects). These template files can be modified to produce custom output. To revert to the default templates, simply remove them and run Lexakai again.
bill-of-materials
lexakai
lexakai-standalone
Copyright © 2011-2021 Telenav, Inc. Distributed under Apache License, Version 2.0
This documentation was generated by Lexakai. UML diagrams courtesy of PlantUML.