From f05d7902e2c273d7f1d31e9e61bbf34ff0a54ecd Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Tue, 15 Oct 2019 08:32:48 +0200 Subject: [PATCH] Polish "Clarify formatting recommendations for configuration property javadoc" See gh-18578 --- .../src/main/asciidoc/spring-boot-features.adoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 2b469da026b..8368cf07501 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -7110,6 +7110,8 @@ Make sure that configuration keys are documented by adding field javadoc for eac } ---- +NOTE: You should only use simple text with `@ConfigurationProperties` field Javadoc, since they are not processed before being added to the JSON. + Here are some rules we follow internally to make sure descriptions are consistent: * Do not start the description by "The" or "A". @@ -7118,9 +7120,6 @@ Here are some rules we follow internally to make sure descriptions are consisten * Use `java.time.Duration` rather than `long` and describe the default unit if it differs from milliseconds, e.g. "If a duration suffix is not specified, seconds will be used". * Do not provide the default value in the description unless it has to be determined at runtime. -NOTE: You should only use simple text with `@ConfigurationProperties` field Javadoc, since -they are not processed before being added to the JSON. - Make sure to <> so that IDE assistance is available for your keys as well. You may want to review the generated metadata (`META-INF/spring-configuration-metadata.json`) to make sure your keys are properly documented. Using your own starter in a compatible IDE is also a good idea to validate that quality of the metadata.