Java: Automate Your Documentation Process
By admin on Sep 28, 2008 in Java, open source, Programming
In any project, documentation is definitely necessary. Problem is that software documentation is always out of sync with the software itself as software is ever evolving. Software documentation is always outdated if they are managed in a manual way.
Here are some open source software that can be used to automate software documentation, and thus avoid inconsistencies between software and its documentation.
Source Code
On the code level, you can use UMLGraph to generate UML diagrams from your source code. UMLGraph allows the declarative specification and drawing of UML class and sequence diagrams. It can be integrated into Ant or Maven to generate UML diagram from your source code, together with JavaDoc.
Besides JavaDoc, Doxygen is an alternative for you to document your Java source code.
Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.
Database
For the database, you can use SchemaSpy and LiquiBase.
SchemaSpy is a Java-based tool (requires Java 5 or higher) that analyzes the metadata of a schema in a database and generates a visual representation of it in a browser-displayable format. It lets you click through the hierarchy of database tables via child and parent table relationships as represented by both HTML links and entity-relationship diagrams. It’s also designed to help resolve the obtuse errors that a database sometimes gives related to failures due to constraints.
LiquiBase is an open source (LGPL), DBMS-independent library for tracking, managing and applying database changes. It is built on a simple premise: All database changes (structure and data) are stored in an XML-based descriptive manner and checked into source control.
Build
Grand (Graphical Representation of ANT dependencies) is a tool to create visual representation of ant target dependencies. It differs from tools like Vizant or AntGraph by a totally different approach, relying on the Ant API rather than parsing directly the XML files. This enables Grand to provide some nifty features such as the support of the ant 1.6.x tasks like import or subant.
User Documentation
For user documentation, you can consider using DocBook.
DocBook is an XML vocabulary that lets you create documents in a presentation-neutral form that captures the logical structure of your content. Using free tools along with the DocBook XSL stylesheets, you can publish your content as HTML pages and PDF files, and in many other formats.
Code Quality Documentation
For this, you can either use QALab or Sonar.
QALab collects and consolidates data from several QA tools and keeps track of them overtime. This allows developers, architects and project managers alike to be presented with a trend of the QA statistics of their project.
The following tools are currently supported:
- Checkstyle: code style validation and design checks. QALab keeps track of number of violations per file and overall.
- PMD: Code checks (possible bugs, dead code, sub-optimal code, etc). QALab keeps track of number of violations per file and overall.
- PMD CPD: Duplicate code (always a bad idea) detection. QALab keeps track of number of the overall number of duplicated lines.
- FindBugs: fantastic tool to detect potential bugs (really!). QALab keeps track of number of violations per file and overall.
- Cobertura: Coverage tool. QALab keeps track of percentage of branch and line coverage.
- Simian: excellent duplicate code detection (non-open source). QALab keeps track of number of the overall number of duplicated lines.
Sonar is an open source entreprise quality control tool, distributed under the terms of the GNU Lesser General Public License. Its basic purpose is to join your existing continuous integration tools to place all your Java development projects under Quality control.
Sonar is based on the following great Open Source projects :
- JavaNCSS
- CheckStyle
- PMD
- Cobertura
- Maven
Other tools include XRadar and Maven Dashboard Report Plugin
For the above tools, combining them with a Continuous Integration Server, you can further automate the process of software documentation.
Sorry, comments for this entry are closed at this time.