Log4j Docgen

Log4j Docgen (Documentation Generation) bundles utility classes to generate documentation from Log4j plugins. Given almost all Log4j functionality (layouts, appenders, etc.) is implemented in the form of plugins, this project aims the following goals:

Avoid the need to maintain documentation in multiple places

For instance, Log4j JSON Template Layout is composed of several plugins with sufficient Javadoc explaining their behaviour. Next to this we also maintain a big json-template-layout.adoc page for the website, again, documenting each component. By generating documentation from the source code, developers can precisely capture the behaviour of their components only in the very code itself that they change.

Accurately capture the component configuration

It is pretty common that source code changes are not reflected to documentation. By generating the documentation from the source code, this discrepancy gets removed.

Dependencies

You need to have the org.apache.logging.log4j:log4j-docgen dependency in your classpath:

<plugin>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-docgen</artifactId>
  <version>0.9.0</version>
</plugin>

Descriptor generator

DescriptorGenerator is an annotation processor that generates an XML file capturing all the metadata needed to document a plugin:

  • types – types it extends from, types it uses in its configuration, etc.

  • configuration – extracts the necessary set of elements, attributes, etc. from builder classes, @PluginFactory-annotated methods, etc.

  • documentation – extracts the Javadoc of each field and type, and converts it to AsciiDoc

Users are recommended to integrate this annotation processor into their build:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths combine.children="append">
      <!-- Include `org.apache.logging.log4j.docgen.processor.DescriptorGenerator` that generates `log4j-plugins.xml`.
           `DescriptorGenerator` must precede `PluginProcessor`, since the latter *claims* the `@Plugin`.
           Once claimed, `javac` doesn't pass those sources to other processors. -->
      <path>
        <groupId>org.apache.logging.log4j</groupId>
        <artifactId>log4j-docgen</artifactId>
        <version>0.9.0</version>
      </path>
      <!-- `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` for generating `META-INF/org/apache/.../Log4j2Plugins.dat`: -->
      <path>
        <groupId>org.apache.logging.log4j</groupId>
        <artifactId>log4j-core</artifactId>
        <version>${project.version}</version>
      </path>
    </annotationProcessorPaths>
    <compilerArgs combine.children="append">
      <!-- Provide `org.apache.logging.log4j.docgen.processor.DescriptorGenerator` arguments: -->
      <arg>-Alog4j.docgen.descriptorFilePath=${project.build.directory}/${project.artifactId}-plugins.xml</arg>
      <arg>-Alog4j.docgen.groupId=${project.groupId}</arg>
      <arg>-Alog4j.docgen.artifactId=${project.artifactId}</arg>
      <arg>-Alog4j.docgen.version=${project.version}</arg>
      <arg>-Alog4j.docgen.description=${project.description}</arg>
      <arg>-Alog4j.docgen.typeFilter.excludePattern=^java\..+</arg>
    </compilerArgs>
  </configuration>
</plugin>

Documentation generator

DocumentationGenerator receives

  1. plugin descriptors (generated by the DescriptorGenerator)

  2. FreeMarker templates (to render the type hierarchy and each individual type)

as input arguments, and produces an AsciiDoc-formatted documentation that one can integrate into the website of a project.

Users are recommended to use the generate-documentation goal of the log4j-docgen-maven-plugin instead.

Schema generator

SchemaGenerator receives plugin descriptors (generated by the DescriptorGenerator) as input, and produces an XSD describing the structure defined by the descriptors.

Users are recommended to use the generate-schema goal of the log4j-docgen-maven-plugin instead.