PropDoc

Introduction

PropDoc is a utility that aims to improve the documentability of Java Properties files. It can read in a standard Java Properties file and parse JavaDoc-like annotations out of the comments of properties. Result is a meta-model that can be used to generate documentation about the properties in the file.

Usage

What you need

1. Maven 2+
2. git

Checking out the code

~$ git clone git://github.com/mrvisser/prop-doc.git

Compiling the jar file

~$ cd prop-doc
~/prop-doc$ mvn install

Sample Properties File

/path/to/file.properties:

##
# This is the description of the property. Since it was not preceded with an annotation, it gets dumped into
# a "description" meta-key that holds all orphaned comments.
#
# @values 1-10
# @default 5
##
my.property.key=5

Using the API

Java Code:

InputStream is = null;
PropDoc propDoc = null;
try {
	is = new FileInputStream("/path/to/file.properties");
	propDoc = new PropDoc(is);
} finally {
	if (is != null) {
		is.close();
	}
}

for (Property prop : propDoc) {
	System.out.printf("Property '%s' has a default of '%s'", prop.getKey(), prop.getMetadataValue("default"));
}

This program using the properties file example above would output:

Property 'my.property.key' has a default value of '5'

Using the velocity processor

The Velocity processor allows you to use a velocity template to generate documentation about your properties file. When you run the following maven command in the root of the source tree:

~/prop-doc$ mvn assembly:single

It should generate you a JAR file in the target/ directory similar to prop-doc-1.0-jar-with-dependencies.jar. This jar is executable, defaulting to the Velocity template propdoc executor:

~/prop-doc$ java -jar target/prop-doc-1.0-jar-with-dependencies.jar
Usage: java \
	-Dpropdoc.output.path=<output propdoc file-system path> \
	-Dproperties.file.url=<source properties file URL> (e.g., file://C:\Temp\config.properties; e.g., classpath:org/my/config/config.properties)\
	[-Dvelocity.template.url=<velocity template url> (e.g., file://C:\Temp\propdoc.vm; default: classpath:ca/mrvisser/propdoc/velocity/template.html.vm)]\
	-jar <prop-doc-1.0-jar-with-dependencies>.jar

propdoc.output.path: The destination for the velocity template output

properties.file.url: A URL for the properties file to use as input. This uses the Java standard URL (protocol+path) formatting, with the addition of the classpath: protocol for classpath resources.

velocity.template.url: The velocity template to use to generate the output. The velocity template has 2 elements in context:

1. $propDoc - this is the propDoc object generated by parsing the properties file
2. $allAttributes - this is a collection of all meta attributes that were found across all property definitions

The default velocity template generates a simple HTML document: https://github.com/mrvisser/prop-doc/blob/master/src/main/resources/ca/mrvisser/propdoc/velocity/template.html.vm but you are free to write your own.