DevOps Zone is brought to you in partnership with:

I am a senior software architect specializing currently in enterprise Java development. I have past experience with JavaScript, python, C and going back in time even FORTRAN and assembly were still not extinct at the start of my career. Currently I work on different customer projects on behalf of EPAM system leading a 8 person agile group. As a hobby independently from my employer I maintain and develop open source projects, like ScriptBasic Classic, ScriptBasic for Java, License3j (google them if interested). Peter is a DZone MVB and is not an employee of DZone and has posted 31 posts at DZone. You can read more from them at their website. View Full User Profile

Documenting API using Concordion

03.23.2014
| 3757 views |
  • submit to reddit

Concordion is an open source tool for writing automated acceptance tests in Java.” It is a handy little tool, simple to use and even the source code of the tool is good style. You describe the tests using HTML with special markups and when you run your special unit tests using the ConcordionRunner it processes the HTML and replaces the special tags with the actual values fetched from the tests. In the end you get an HTML colored with red and green spots where some tests failed or succeeded respectively. This is a result good for the eyes, BAs and easy to spot any error. This way it is similar to fitnesse and GreenPepper.

Even though the tool was designed for automated acceptance test — which one could argue is a non-sense term — I wanted to use it to document API.

The usual way to document API is JavaDoc. JavaDoc includes the signature of the methods, and comments. The comments are supposed to depict the way the method should be used. This is fairly good approach but has some shortages:

  • The comments become outdated. Developers change the way the method is to be used, but forget to update the JavaDoc.
  • A method many times should be used in different ways together with other objects and methods.

For this reason many developers believe that unit tests are the real documentation of an API. Two approaches with good and bad aspects. How could we leverage the best of the both world?

I decided to write a small library that can be included into Concordion fixtures using delegation and which can read the source code of the fixture or just any other source code, cut off some lines from the code and return them as string. Referencing the method Concordion output can include (presumably preformatted) Java code. This way the resulting HTML will contain living documentation including actual code without manual copy pasting that decreases the danger of the documentation getting outdated.

The project is available from GitHub and also from Sonatype repo. The documentation of the project was also created this way.

Published at DZone with permission of Peter Verhas, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Tags: