[shadowgovt]

> The second point doesn't seem like a positive on the whole, except maybe for the company selling it, in the "there's good money to be made in being part of the problem" sense.

No argument there (I don't miss those firm's doc standards). But you can make a lot of money being part of the problem in the business universe.

> The comment gives the appearance of being helpful while actually just adding confusion and wasting everyone's time.

That's definitely a concern; if the tool doesn't work it doesn't work, potential or no.

I think the first comment (https://github.com/spring-projects/spring-boot/pull/39754/fi...) looks helpful, although it is repeating info you can find in the class docs, the fact you have to go to the class docs to find it is an issue. A tool that could on--the-fly generate "Give me context for this function" (and give the right output) would be pretty useful for comprehending a codebase.

[ptx]

I don't know about that one. As you say, it's just repeating the class documentation, so maybe the tooling should make it easier to view the class docs if that's the problem. The generated version is also less clear: In what sense are the conventions "necessary"? The process "includes" the steps listed, but does it also include other things?