Improve how to configure configuration keys of a custom starter

Closes gh-17573

Author: snicoll

spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -8403,16 +8403,55 @@ assume that you are creating a starter for "acme" and that you name the auto-con
 module `acme-spring-boot-autoconfigure` and the starter `acme-spring-boot-starter`. If
 you only have one module that combines the two, name it `acme-spring-boot-starter`.
 
-Also, if your starter provides configuration keys, use a unique namespace for them. In
+
+
+[[boot-features-custom-starter-configuration-keys]]
+==== Configuration keys
+If your starter provides configuration keys, use a unique namespace for them. In
 particular, do not include your keys in the namespaces that Spring Boot uses (such as
 `server`, `management`, `spring`, and so on). If you use the same namespace, we may modify
-these namespaces in the future in ways that break your modules.
+these namespaces in the future in ways that break your modules. As a rule of thumb,
+prefix all your keys with a namespace that you own (e.g. `acme`).
+
+Make sure that configuration keys are documented by adding field javadoc for each
+property, as shown in the following example:
+
+[source,java,indent=0]
+----
+	@ConfigurationProperties("acme")
+	public class AcmeProperties {
+
+		/**
+		 * Whether to check the location of acme resources.
+		 */
+		private boolean checkLocation = true;
+
+		/**
+		 * Timeout for establishing a connection to the acme server.
+		 */
+		private Duration loginTimeout = Duration.ofSeconds(3);
+
+		// getters & setters
+
+	}
+----
+
+Here are some rules we follow internally to make sure descriptions are consistent:
+
+* Do not start the description by "The" or "A".
+* For `boolean` types, start the description with "Whether" or "Enable".
+* For collection-based types, start the description with "Comma-separated list"
+* 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.
 
 Make sure to
 <<appendix-configuration-metadata#configuration-metadata-annotation-processor,trigger
 meta-data generation>> so that IDE assistance is available for your keys as well. You may
-want to review the generated meta-data (`META-INF/spring-configuration-metadata.json`) to
-make sure your keys are properly documented.
+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.