Better documentation for configuration properties

[dsyer]

I don't know if this is completely resolvable in Spring Boot but I've noticed that quite a few important features are hard to find documentation or implementation details for. Example endpoints.default.enabled. The docs basically say that it enables endpoints (well duh). What does it actually do? How does it differ from endpoints.web.default.enabled? It's probably guarding a @Conditional somewhere. Maybe it would be useful to see where?

Part of this is features showing up in additional-spring-configuration-metadata.json (e.g. in spring-boot-actuator-autoconfigure), where the IDE (STS anyway) doesn't support linking to relevant source code. The metadata isn't there to create a link - these files are curated by hand, so I guess if there is a way for the IDE to link to something in source code it would be useful to add it.

Another problem is "deprecation" in spring-configuration-metadata.json where we have seen quite a few properties where the alternatives are not really even mentioned, never mind documented. There is a "reason" tag in the deprecation metadata, but it's not really a reason that the user needs, it's an alternative.

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.

[snicoll]

I think there are several parts in this issue and I'd like them to be handled separately.

I would like to see some concrete proposal to make the current descriptions better. We need the first sentence to be concise (as it shows up in the auto-completion form). Also that thing is not supposed to replace the documentation (the example you're using is a milestone feature for which the doc is not ready yet). If you only look in your IDE to understand what a feature does, this is a problem IMO. I am happy to review a PR for the descriptions that you find confusing.

I am not keen to have any sort of link between key and code. First, there is nothing that states the consumer of the metadata is a full fledged IDE. Then, if we have to link our users explicitly to code, something else is wrong IMO.

There is no one-to-one mapping between old and new properties. If there was one, we'd read the old property and flag it as deprecated (not error). The purpose of the error level and the reason field is to give you more explanation right from the IDE:

1. The property will not work, defining it will no longer have an effect
2. The feature is removed or has changed (hint: look at the migration guide, the release notes, etc). The reason is an initial pointer so that you know what is going on. If the current reasons suck we can fix them or, better yet, you can propose something.

I like the idea of links. We've recently done that on start.spring.io and I think it's quite useful to put things in perspective. I don't know if I want to write link in Javadoc but this is something I am happy to debate.

[wilkinsona]

First, there is nothing that states the consumer of the metadata is a full fledged IDE.

I don't think we should let that stop us from providing links (to code, documentation, whatever) if we think that's the right thing to do. Both Markdown and Asciidoc show that it's possible to write text with links that remains readable when viewed in a form where the links don't actually link anywhere.

hint: look at the migration guide, the release notes, etc

If the hint is to go hunting and looking in multiple places then I think we could do better. Perhaps this all ends up in the migration guide, but I think it's important that it isn't spread across release notes, blog posts, reference documentation etc.

[snicoll]

Sorry for the confusion.

Both Markdown and Asciidoc show that it's possible to write text with links that remains readable when viewed in a form where the links don't actually link anywhere.

I only meant that as a reference to source code. If you want to link to code, you need a full fledged IDE and I don't think we should do that anyway. I very much like the idea of providing links to content (documentation, sample, etc).

If the hint is to go hunting and looking in multiple places then I think we could do better.

Of course and that's not what I meant. What I mean is that application.properties shouldn't be the primary source for the information related to an upgrade. It certainly can warn you about things being removed or changed (depending on the feature) but not tell you how to upgrade. Not everything is based on a key anyway.

[philwebb]

It's quite hard to action this issue because it contains quite a few suggestions. I'll close it for now and we can add new issues for things we can actually do if we feel they are important.

• Improve descriptions for properties that are too terse (do on a case-by-case basis)
• Improve formatting for descriptions (allow full Javadoc or markdown)
• Provide links to relevant sections of the documentation

(please link any new issues back to this one)