conf-doclet

Java Doclet for extracting configuration properties and their default values from java code.

Usage

Configuration

Add the next code to the build.gradle file: ```groovy repositories { maven { url "http://epages-de.github.com/maven-repo/releases" } }

configurations { confDoclet }

dependencies { confDoclet "com.epages.doclets:conf-doclet:0.1" }

task confDoc(type: Javadoc) { classpath = rootProject.configurations.confDoclet classpath += files(subprojects.collect { project -> project.sourceSets.main.compileClasspath }) options.showAll() destinationDir = new File(buildDir, 'docs/confdoc') options.docletpath = configurations.confDoclet.files.asType(List) options.doclet = "com.epages.doclets.ConfDoclet" options.addStringOption("outputFile", "sample.conf") options.addBooleanOption("excludePropWithUndefinedDefaults", true) }

<h5>Additional Options</h5>
Beside the javadoc options, there are some other additional ones, specific to this Doclet:

* <b>outputFile</b> - the name of the output file
* <b>excludePropWithUndefinedDefaults</b> - the detected properties which have no default values are added to the generated file by default. If this property is set, these properties will be excluded from the generated file.

<h4>Example</h4>

To actually extract the configuration properties from the java source code, you have to follow some conventions
in your configuration classes: <br>
* the <code>@ConfigurationSection</code> javadoc taglet in the class comment
* the defined properties (can even be PRIVATE) with their corresponding DEFAULT values (propertyName + "_DEFAULT").<br>
* the defined properties need to be <b>STATIC</b> and <b>FINAL</b>

```java
   /**
     * section comment
     * @ConfigurationSection PropertySection
     */
    public class ConfigClass {
        /**
    	 * comment 1
    	 */
    	private static final String PROPERTY_1 = "property1";
    	/**
    	 * comment 2
    	 */
    	private static final String PROPERTY_2 = "property2";
    	
    	
    	private static final String PROPERTY1_DEFAULT = "default value of property1";
    	private static final String PROPERTY2_DEFAULT = "default value of property2";
    }

Output

With all of the above configured, the output will be a sample.conf file containing

;;section comment
[PropertySection]
;;comment 1
;PropertySection.property1 = default value of property1

;;comment 2
;PropertySection.property2 = default value of property2

The number of classes with the @ConfigurationSection taglet, will be reflected in the number of [Section]s in the output file.

Gradle Command Line

```groovy > gradle confDoc ```

Limitations

The default values can only be primitives. No objects supported. If an object is encountered for a default value, the default value is set to an empty string and a warning message will be printed.