Improve document to elaborate why the slash in the map key will be removed

[quaff]

spring-boot/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/external-config.adoc

Lines 914 to 915 in 50d0519

	When binding to `Map` properties you may need to use a special bracket notation so that the original `key` value is preserved.
	If the key is not surrounded by `[]`, any characters that are not alpha-numeric, `-` or `.` are removed.

It would be nice if more words here to show the motivation.

[quaff]

Further more, if possible, I think it should raise error with meaningful message instead of removing characters silently.

[wilkinsona]

We documented when and why the special bracket notation is needed in #13506. This was then refined in #23390. I don't think we should get into the why in the reference documentation. My feeling is that it's a level of detail that the vast majority of users don't need and it will make the documentation unnecessarily verbose. Let's see what the rest of the team thinks.

[mhalbritter]

I agree with Andy. I think we should document the observable behavior, and not necessarily the why.

[quaff]

We documented when and why the special bracket notation is needed in #13506. This was then refined in #23390. I don't think we should get into the why in the reference documentation. My feeling is that it's a level of detail that the vast majority of users don't need and it will make the documentation unnecessarily verbose. Let's see what the rest of the team thinks.

How about adding a link to #23390?

[snicoll]

We shouldn't link the issue tracker from our reference doc. I also think that it would make the doc unnecessarily verbose.

[bclozel]

With my vote, this makes the majority of the team. Sorry @quaff but the reference docs are not meant to track design decisions and tradeoffs but rather describe how things work.

[quaff]

Further more, if possible, I think it should raise error with meaningful message instead of removing characters silently.

@philwebb How about this proposal?

The current behavior is counter-intuitive, there are several issues that reporter is confused by my.map./key3=value3 is mapped as key3=value3, exception should be thrown to state that last element of the ConfigurationPropertyName should be written as ElementType.INDEXED instead of ElementType.NON_UNIFORM, better than documenting that, not everyone read document before writing code.
It's indeed a breaking change, but I doubt someone would rely on such quirk behavior, it's not worthy to make it as an opt-in feature.

EDIT: I created prototype https://github.com/spring-projects/spring-boot/compare/main...quaff:spring-boot:patch-87?expand=1