Formatting and links in configuration properties metadata

[dsyer]

Configuration properties metadata is intentionally minimally formatted. This causes problems and confusion for library authors because they want to write normal javadocs. I don't know if there's anything that can be done about that, but maybe we can do something simpler that would help. Perhaps a new feature to link to some more documentation (URLs could be automatically converted to links by IDEs for instance)? That way the javadocs and the JSON could stay terse, but users would be able to find more documentation quickly, as long as it was supported in the IDEs.

See #10930

[philwebb]

PR #6226 made a start on cleaning the Javadoc. Ideally it would be nice if a limited subset of javadoc markup could be used. We'll need to put the formatted version in a different part of the JSON so that existing tools don't break.

[YannCebron]

Please consider that "javadoc" will not work for configuration properties defined in Kotlin (or possibly other JVM languages which expand "plain"/"HTML" markup). see https://kotlinlang.org/docs/reference/kotlin-doc.html#inline-markup

[philwebb]

Thanks for the heads-up