Generate reference documentation and XSD from metadata

[ppkarwasz]

Log4j plugins follow a slightly modified JavaBean model. As a first step of #1954 we should:

• research the available metadata formats that could be employed to document Log4j plugins,
• choose the most appropriate metadata format based on: maintenance state, available tools and features. An in-house solution should have lowest priority (cf. NIH),
• use an example metadata file to generate an XSD schema,
• use an example metadata file to generate reference documentation pages.

[ppkarwasz]

A loose list of metadata formats we might consider:

• an XML Schema itself,
• a Plexus component descriptor,
• a Maven plugin descriptor, which is used by the Maven Plugin plugin to generate documentation,
• a Modello model that can be converted in many other formats,
• Tomcat MBean descriptors,
• OSGI Declarative Services descriptors,
• maybe the Eclipse Modelling Framework can help, although it seems like an overkill.

[vy]

A loose list of metadata formats we might consider:

• an XML Schema itself,
• a Plexus component descriptor,
• a Maven plugin descriptor, which is used by the Maven Plugin plugin to generate documentation,
• a Modello model that can be converted in many other formats.

@ppkarwasz, I completely support the research phase you described. Though I will also appreciate some non-Maven-native solutions (besides an XSD) too.

[ppkarwasz]

@ppkarwasz, I completely support the research phase you described. Though I will also appreciate some non-Maven-native solutions (besides an XSD) too.

Sure thing, my research is not complete. Maven-related formats were just the easiest to find.

[jvz]

Neat, this is an idea I've had in the past. It would be great if we had proper XSDs that made it easier to edit a log4j configuration file. Might be useful to see if this schema can be represented as a JsonSchema, too, so it can be used for JSON and YAML configuration files.

One potential source of inspiration here would be whatever Spring Boot does for making your various @ConfigurationProperties classes autocomplete when modifying Spring properties configurations.

I should note that various old plugins still use strings for various plugin attributes that should be a different data type, but the initial plugin system only supported string values for attributes as it mimicked the DOM API here. Thus, if you use the type info of a plugin attribute, note that a string type is not necessarily authoritative.

[ppkarwasz]

The main plan here is to have a documentation like Maven plugins (e.g. Maven Compiler Plugin). These are generated without a single line of text (besides the *.java files). I would like something like this for each plugin:

Parameter	Type	Description
direct	boolean	Specifies whether to use System.out/err or the file descriptors
layout	Layout	The layout to use. Common layouts: list of links. (all layouts link)

The XSD will be a byproduct of this process, but the metadata must be a little bit larger: in February-March we plan to write an online configuration builder/validation tool. This tool might also spit up a list of Maven dependencies required by the configuration.

[jvz]

Oh that all sounds fantastic!

[ppkarwasz]

Our plugins can be approximately modeled as JavaBeans, i.e. as Java classes with a set of documented properties, so a descriptor of a Log4j plugin must allow:

• to describe a class and its hierarchy (both superclass and interfaces),
• to describe its properties, which can be primitive Java values, classes or interfaces: our current configuration visitor binds primitive values and Strings by name and other kinds of properties by type.

The second requirement limits the list of available read-to-use component descriptors: Plexus component descriptors do not allow properties of any type. An XSD schema might also not be enough to precisely document our components: there is no standard way to convey inheritance in an XSD. We should probably leave XSD as a product of our documentation process.

[ppkarwasz]

A second requirement from the metadata format is the availability of tools to generate various formats of documentation:

• as far as I can tell OSGi Declarative Services do not have such tools,
• the was an Eclipse EMF documentation generator, but it does not seem available at the moment,
• Tomcat Configuration Reference, which was the main inspiration for this task is actually generated manually (cf. git repository).

This leaves Modello that has an impressive number of generators and the custom Maven Plugin descriptor as contenders. The documentation of Maven Plugin descriptor is actually generated by Modello.