Generated config documentation

Before you start

In order to be able to start with config generator, one will need to add the following dependencies to the module:

This dependency contains the required annotations itself:

<dependency>
   <groupId>io.helidon.config</groupId>
   <artifactId>helidon-config-metadata</artifactId>
   <scope>provided</scope>
   <optional>true</optional>
</dependency>

This dependency is a compile-time annotation processor which creates config-metadata.json under the META-INF/helidon. This generated file is needed later for an actual config documentation creation.

<dependency>
   <groupId>io.helidon.config</groupId>
   <artifactId>helidon-config-metadata-processor</artifactId>
   <scope>provided</scope>
   <optional>true</optional>
</dependency>

One will also need to add the following line to the module module-info.java

requires static io.helidon.config.metadata;

Helidon module preparation

In the Helidon module, one want to generate documentation for, identify all the builders, which are configurable using config.

Builder

Each builder, one wants to generate documentation for, needs to have a @Configured annotation specified. Sometimes it is sufficient to annotate the builder with just @Configured annotation, without any other parameters. But if you want to configure a little more information about the builder and format of the configuration it is expected it to have, one can use annotation parameters present on the @Configured.

Example

@Configured(root = true, prefix = "client", description = "Configuration of the HTTP client")

Config property

Each of the builder methods, which are configurable by the config, should have @ConfiguredOption specified.

Example 1

If the annotation is set without any specific parameters, config key is taken out of the method name, type value is take from the parameter type and description is taken out of the method Javadoc.

Given builder method

/**
* Sets a new host value.
*
* @param host host
* @return updated builder instance
*/
@ConfiguredOption
public Builder host(String host) {
}

Generates following entry

key	type	default value	description
host	string		Sets a new host value.

If the parameter method type is another configurable object, the tool will generate link between the two config documentations.

Example 2

In case one needs to configure generated entry more, it can be done with usage of different parameters @ConfiguredOption provides.

Given builder method

/**
* Sets new connection timeout.
*
* @param connectTimeout connection timeout
* @return updated builder instance
*/
@ConfiguredOption(key = "connect-timeout-millis", type = Long.class, value = 123, description = "Request connection timeout")
public Builder connectTimeout(Duration connectTimeout) {
}

Generates following entry

key	type	default value	description
connect-timeout-millis	long	123	Request connection timeout

Config Documentation Generation

Clone the following project: https://github.com/tomas-langer/config-documentation and read project README.

All the documentation should be generated to the docs/shared/config in the Helidon project.

Documentation file created this way, can be referenced from the technology/module adoc file with the following line:

include::{ path to the docs/shared/config }/GeneratedDocFileName.adoc[]

Known issues

• Generated files names are not of the builded type, but of the builder itself. io.helidon.webclient.Proxy.Builder.adoc instead of just io.helidon.webclient.Proxy.adoc
• Linking between generated configuration files (as mentioned in Example 1) does not work properly now.