@ConfigurationProperties - Grab javadoc from setter/getter if no field javadoc exists

[davsclaus]

When using @ConfiguraitonProperties on custom configuration classes, then you may have documentation on the fields in the getter or setter methods. The latter is a common practice.

The APT that generates the JSon schema file grabs only the javadoc from the field itself, according to: https://github.com/spring-projects/spring-boot/blob/master/spring-boot-tools/spring-boot-configuration-processor/src/main/java/org/springframework/boot/configurationprocessor/ConfigurationMetadataAnnotationProcessor.java#L262

At the Apache Camel project we also have an APT that generate some Camel stuff. We also grab javadoc as documentation but we look for the javadoc at

• field
• setter
• getter
• fluent builder style

In that order. You can find our APT code at: https://github.com/apache/camel/blob/master/tooling/apt/src/main/java/org/apache/camel/tools/apt/AbstractAnnotationProcessor.java#L57

If this has interrest to the Spring Boot project, then we could enhance Spring so it can also look for the javadoc coumentation in some or all of the above. By looking for the javadoc in the setter/getter would help many users as a start.

I could also not find any code in spring boot that may sanitize the javadoc to removed invalid content when its being saved into the JSon file. We at Apache Camel has some code than clean the javadoc to make it JSon safe: https://github.com/apache/camel/blob/master/tooling/apt/src/main/java/org/apache/camel/tools/apt/helper/JsonSchemaHelper.java#L208

[snicoll]

The cleaning part might be of interest, thanks. As for the documentation, I think we prefer to keep a separate ("unusual") location. Let's see what others say.

[davsclaus]

Thanks for the feedback.

So we at Apache Camel then could not reuse our existing configuration classes out of the box, as they have javadoc documentation on the setters / fluent builders - eg the APIs that the end users would use when he/she is writing code and calling the setter or fluent builder.

So we came up with generating spring boot configuration classes and copy the javadoc into the fields instead of getter/setter etc.

In case anyone is curious then these java classes is generated https://github.com/apache/camel/tree/master/components/camel-ahc/src/main/java/org/apache/camel/component/ahc/springboot

And the spring.factories as well https://github.com/apache/camel/blob/master/components/camel-ahc/src/main/resources/META-INF/spring.factories

[snicoll]

So we at Apache Camel then could not reuse our existing configuration classes out of the box, as they have javadoc documentation on the setters / fluent builders - eg the APIs that the end users would use when he/she is writing code and calling the setter or fluent builder.

That's one way to see it. Another way to see it is that usual getter/setter javadoc is not a good target for configuration key description. The value of the documentation ends up in the content assistance auto-completion and you want the first sentence to be as coherence and concise as possible. That's not what you have in mind when writing getter/setter javadoc (IMO). I've added this issue for team discussion which should happen this week still.

[snicoll]

The outcome of the discussion is that we first need to sanitize the Javadoc. Could you please contribute the code that sanitize the Javadoc in a PR? We won't have time for 1.4 but I'd like to give a try to interface-based @ConfigurationProperties in 1.5 and we'll have to fetch the Javadoc from the getter anyway. At this point, it makes sense to have an opt-in mechanism to also look at getter for regular class. I'll have to check if passing config to an annotation processor is as painful as I remember.

[davsclaus]

Yes I can do a PR with the javadoc clean code. I will be traveling this week, but will be back in the office next week.