fuhouyin/spring-boot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document when defaultValue and description cannot be extracted

Browse Source 
Closes gh-43925
This commit is contained in:
Andy Wilkinson 2025-01-22 14:50:53 +00:00
parent a3eaafbbea
commit 390963fe74
1 changed files with 8 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc
View File

@ -98,14 +98,20 @@ Consider the following example:
include-code::MyServerProperties[]
This exposes three properties where `my.server.name` has no default and `my.server.ip` and `my.server.port` defaults to `"127.0.0.1"` and `9797` respectively.
The Javadoc on fields is used to populate the `description` attribute. For instance, the description of `my.server.ip` is "IP address to listen to.".
The Javadoc on fields is used to populate the `description` attribute.
For instance, the description of `my.server.ip` is "IP address to listen to.".
The `description` attribute can only be populated when the type is available as source code that is being compiled.
It will not be populated when the type is only available as a compiled class from a dependency.
For such cases, xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.adding-additional-metadata[manual metadata] should be provided.
NOTE: You should only use plain text with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] field Javadoc, since they are not processed before being added to the JSON.
If you use javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] with record class then record components' descriptions should be provided via class-level Javadoc tag `@param` (there are no explicit instance fields in record classes to put regular field-level Javadocs on).
The annotation processor applies a number of heuristics to extract the default value from the source model.
Default values have to be provided statically. In particular, do not refer to a constant defined in another class.
Default values can only be extracted when the type is available as source code that is being compiled.
They will not be extracted when the type is only available as a compiled class from a dependency.
Furthermore, default values have to be provided statically. In particular, do not refer to a constant defined in another class.
Also, the annotation processor cannot auto-detect default values for ``Enum``s and ``Collections``s.
For cases where the default value could not be detected, xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.adding-additional-metadata[manual metadata] should be provided.