-
Notifications
You must be signed in to change notification settings - Fork 44
Mind Map annotation processor
Since 1.6.0 it is possible to mark Java code by source level annotations. Special annotation processor can find source level annotations during compilation phase and generate MMD files.
Package com.igormaznitsa:mind-map-annotations:1.6.8 contains set of source level annotations which allows mark different source elements and generate MMD files based on marking annotations. All annotations source level ones so that they play role only during build process. As example you can see sources of tests for the tool.
Annotation MmdFile is very important one because describes MMD file and allows to provide path for it, root topic info and another auxiliary information.
The annotation provides way to point already defined MmdFile annotation through UID or a class contains such annotation.
The annotation describes one mind map node and it desires a mmd file to be added. Processor will be looking for MmdFile annotation through hierarchy and first one will be uaed as the target to place the node.
Annotation processor provided in maven central repository as com.igormaznitsa:mind-map-annotation-processor:1.6.6 and should be attached to build process.
Processor provides number of options which allow tune process and result.
- mmd.target.folder - parameter provides target folder where all generated MMD files should be collected, if it is not provided then MMD files will be generated next to files contain their source MmdFile annotation.
- mmd.file.link.base.folder - parameter allows define base project root folder which is very important if you going to use SciaReto editor or plug-ins to view content and jump through file links, because the folder will be used as base to calculate relative path.
- mmd.file.root.folder - folder resticts possibility to create new files, play security role if defined and close way to create files in unexpected places. If not defined then value from mmd.target.folder will be used.
- mmd.dry.start - boolean flag if true then process will be started in dry mode, i.e. all annotations and files will be processed but no any result will be created, can be used for diagnostic purposes. Default is false
- mmd.folder.create - boolean flag allows create folder defined in mmd.target.folder if true, else process failed if target folder not exists. Default is false
- mmd.file.overwrite - boolean flag if true then it allows overwrite existing files during processing. By default is true
- mmd.comment.scan - boolean flag if true then allowed analyze of marked method bodies for commentaries containing MMD annotations
- mmd.target.format - format of target documents, it can have multiple values separated by comma (allowed values MMD,MINDMUP,FREEMIND,PLANTUML,SVG,PNG,MD,TXT,ASCIIDOC,ORGMODE)
Keep in mind that file links are built from root maven project for it I use special plugin which finds and provide root folder as property.
Since 1.6.6 version added feature to place marks inside method bodies. Extended scope for MmdTopic annotation to support local variables but also added way to place marks in single line comments to cover code places non-allowed for annotating. Let's take a look at some code snippet:
@MmdTopic(title = "MARKED")
@HasMmdMarkedElements
public int internalTopics() {
//@MmdTopic(colorFill=white,path={"path1","path2","path3"}) pathCommentTopic
@MmdTopic(order = 3)
int a = 0;
@MmdTopic(order = 2)
int b = 1;
@MmdTopic(order = 1)
int c = 3;
//@MmdTopic(order=445) sum
return a + b + c;
}It is code snippet from tests shows how to mark code lines inside method body. As the first one the method should be marked by annotation @HasMmdMarkedElements to signal the annotation processor to analyze method body. In the case the annotation processor extracts annotations for local variables. To analyze annotations placed as line commentaries, there should be added true flag mmd.comment.scan for the processor and it will be analyzing whole method body text to extract annotations placed inside line comments. It is possible place just regular annotation as line comment or some short form like //@MmdTopic Hello world
In case Gradle, just add one more task into your build.gradle. Task called mmddoc. Call of the task will generate mmdDoc folder in root project directory tree and all MMD files will be collected there. It is better to use external folder instead of direct source folder (which in use by default) because IDE can detect changes and result can be different for incremental build.
dependencies {
implementation 'com.igormaznitsa:mind-map-annotations:1.6.8'
}
tasks.register('mmddoc') {
group 'Documentation'
description 'Find MMD annotations among source files and generate MMD maps based on found annotations'
var mmdTargetFolder = new File(rootProject.projectDir, '.knowledgeFolder')
delete(mmdTargetFolder)
logger.info("Target MMD doc folder: {}", mmdTargetFolder)
dependencies {
annotationProcessor 'com.igormaznitsa:mind-map-annotation-processor:1.6.6'
}
compileJava.outputs.upToDateWhen {false}
compileJava.doFirst {
tasks.withType(JavaCompile).tap {
configureEach {
configure(options) {
// base folder for file links in mind map
options.compilerArgs << '-Ammd.file.link.base.folder=' + rootProject.projectDir.getAbsolutePath()
// target folder where place result of work
options.compilerArgs << '-Ammd.target.folder=' + mmdTargetFolder.getAbsolutePath()
// allow create mmd folder if not exists
options.compilerArgs << '-Ammd.folder.create=true'
}
}
}
}
finalizedBy compileJava
}Below you can see code-snipet adding mmddoc profile into build process. Just add it into your pom.xml and execute mvn clean compile -Pmmddoc. In result mmdDoc folder of your root project, you will find all generated mmd files.
<dependencies>
<dependency>
<groupId>com.igormaznitsa</groupId>
<artifactId>mind-map-annotations</artifactId>
<version>1.6.8</version>
<scope>provided</scope>
</dependency>
</dependencies>
<profiles>
<profile>
<id>mmddoc</id>
<properties>
<mmdDoc.folder>.projectKnowledge</mmdDoc.folder>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.commonjava.maven.plugins</groupId>
<artifactId>directory-maven-plugin</artifactId>
<version>1.0</version>
<executions>
<execution>
<id>directories</id>
<goals>
<goal>highest-basedir</goal>
</goals>
<phase>initialize</phase>
<configuration>
<property>mmd.basedir</property>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}${file.separator}${mmdDoc.folder}</directory>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
<executions>
<execution>
<id>clear-mmd-folder</id>
<phase>initialize</phase>
<goals>
<goal>clean</goal>
</goals>
<configuration>
<excludeDefaultDirectories>true</excludeDefaultDirectories>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths combine.children="append">
<annotationProcessorPath>
<groupId>com.igormaznitsa</groupId>
<artifactId>mind-map-annotation-processor</artifactId>
<version>1.6.8</version>
</annotationProcessorPath>
</annotationProcessorPaths>
<compilerArgs combine.children="append">
<compilerArg>-Ammd.target.format=MMD,PLANTUML,PNG</compilerArg>
<compilerArg>-Ammd.file.link.base.folder=${mmd.basedir}</compilerArg>
<compilerArg>-Ammd.target.folder=${project.basedir}${file.separator}${mmdDoc.folder}</compilerArg>
<compilerArg>-Ammd.folder.create=true</compilerArg>
<compilerArg>-Ammd.comment.scan=true</compilerArg>
</compilerArgs>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>