{"id":2531,"date":"2016-08-06T20:29:42","date_gmt":"2016-08-06T19:29:42","guid":{"rendered":"http:\/\/sahits.ch\/blog\/?p=2531"},"modified":"2016-08-06T20:29:42","modified_gmt":"2016-08-06T19:29:42","slug":"documentation-generation-with-the-compiler-api","status":"publish","type":"post","link":"http:\/\/sahits.ch\/blog\/blog\/2016\/08\/06\/documentation-generation-with-the-compiler-api\/","title":{"rendered":"Documentation generation with the Compiler API"},"content":{"rendered":"

Documentation of code has a tendency to become obsolete quickly. For that reason most often the only documentation is the code itself and if you are lucky some JavaDoc that is more or less up to date. For that reason I already started some time ago to generate additional documentation by doing static code analysis on my OpenPatrician<\/a> project. So far this was done mainly with the Reflection API and it was sufficient to figure out what Spring beans there are and where they are used.<\/p>\n

The next documentation task was to figure out which class posts what event type on which EventBus<\/a> and which class handles the event. Or more simple what are the Event producers and what are the Event consumers and mapping them to see how the event messages flow. As the publishing of the events (in the terminology of Guava EventBus ‚post‘) happens within a method, simple reflection will not yield the desired results. Therefore I turned to the Compiler API <\/a>that can be found in the tools.jar. As that API is poorly documented by JavaDoc and there are not that many examples, I decided to write this post as a means to provide another example.<\/p>\n

<\/p>\n

I will not go into the details how the whole retrieval of all relevant information for the documentation task works, but focus on the most complex part, the figuring out which event types are posted on which EventBuses. First of let’s take a look at the class that we want to inspect:<\/p>\n

import com.google.common.eventbus.EventBus;\r\nimport javafx.beans.property.DoubleProperty;\r\nimport javafx.beans.property.IntegerProperty;\r\nimport javafx.beans.property.SimpleDoubleProperty;\r\nimport javafx.beans.property.SimpleIntegerProperty;\r\nimport javafx.beans.property.SimpleLongProperty;\r\n\r\nimport java.util.Random;\r\n\r\npublic class SampleClass {\r\n    private EventBus clientServerEventBus;\r\n\r\n    public void directPost() {\r\n        clientServerEventBus.post(new SimpleLongProperty(47L));\r\n    }\r\n\r\n    public void indirectPost() {\r\n        IntegerProperty s = new SimpleIntegerProperty();\r\n        DoubleProperty event = new SimpleDoubleProperty();\r\n        clientServerEventBus.post(event);\r\n    }\r\n\r\n    public void undecidedInstancePost() {\r\n        IntegerProperty event;\r\n        Random rnd = new Random();\r\n        if (rnd.nextBoolean()) {\r\n            event = new SimpleIntegerProperty(42);\r\n        } else {\r\n            event = new SimpleIntegerProperty(4711);\r\n        }\r\n        clientServerEventBus.post(event);\r\n    }\r\n}\r\n<\/pre>\n
In this example class the event object is created in three different ways:<\/p>\n
    \n
  1. through direct invocation of the constructor as in the method directPost<\/em><\/li>\n
  2. through referencing a variable like in indirectPost<\/em><\/li>\n
  3. through referencing a variable that is uninitialized when defined as in undecidedInstancePost<\/em><\/li>\n<\/ol>\n
    There are still other cases than the three above, however these were the main cases encountered in my code.<\/p>\n
    This excellent article<\/a> started me of in the right direction as it explains, how<\/p>\n