This is a solution for generating message documentation automated based on annotations.
In order to use the following steps will be required:
Integrate the XclDocGenerator annotation processor in our build process for the api project
Use the asciidoclet maven plugin in order to write javadocs using asciidcolet syntax
Describe the message in the java doc for that class using ascidoc syntax
Annotate a class with XclEvent or XclCommand annotations
Annotate a fields with the XclMessageField annotation
At the build time the annotation processor will create a new subfolder called xcldocs on the target folder, wher for each annotated class an asciidoc file will be generated. This files could then be easily integrated on the overall documentation
This is just a proof of concept, sky is the limit. We can add more descrioptors on the annotations, detect fields which are no annotated and should be, extend the types we can process, add links between message classes and so on.
I atached on the sample archive a class (NewOrderCommand) with the annotations added to it, and the generated ascii doc for it.
If you want to look in more detail how the do generator works please check the XclDocGenerator and the XclDocGeneratorTest classes. Just running the test will generate a sample ascidoc file for some test classes.
I think that this will be a very robuts solution to keep our documentation in sync as every developer will be responsible to keep them up to date.
This is a solution for generating message documentation automated based on annotations. In order to use the following steps will be required:
This is just a proof of concept, sky is the limit. We can add more descrioptors on the annotations, detect fields which are no annotated and should be, extend the types we can process, add links between message classes and so on.
I atached on the sample archive a class (NewOrderCommand) with the annotations added to it, and the generated ascii doc for it.
If you want to look in more detail how the do generator works please check the XclDocGenerator and the XclDocGeneratorTest classes. Just running the test will generate a sample ascidoc file for some test classes.
I think that this will be a very robuts solution to keep our documentation in sync as every developer will be responsible to keep them up to date.
samples.zip