5 ms·

> One is that (glancing through the comments) they're actually significantly more thorough than what is already there and they're at the level of thoroughness t

> One is that (glancing through the comments) they're actually significantly more thorough than what is already there and they're at the level of thoroughness that a new user may actually want. Consider this real example from the pull request: /** * Returns the plugin version property. * @return the plugin version property */ @Input public Property<String> getPluginVersion() { return this.pluginVersion; To me this seems less like a useful comment, and more like a joke trying to highlight the absurdity of aiming for complete javadoc coverage.

shadowgovt 3y ago
I agree on that example. But contrast with this example: https://github.com/spring-projects/spring-boot/pull/39754/files#diff-23439aca4bd1fd8e9984f9739b011e128cd4b13f63dc3417786bc82d90ff41d7R70 https://github.com/spring-projects/spring-boot/pull/39754/fi... A function named `apply` with no documentation; you have to go up to the class to find the docs. And yes, it's not DRY to repeat the docs, but the fact the tool can pull relevant context into this location is helpful if it could be used as an on-the-fly doc generator (assuming, of course, it gives true output). People (understandably) don't want to repeat themselves but they also can't predict what entrypoint a reader enters their class from. I've definitely bounced off APIs before because something like `apply` isn't doc'd even though it's doc'd in source twenty lines away (because I'm busy; I'm not scanning entire source files on the off chance that the thing I'm looking for is nearby).
- TheCoelacanth 3y ago
  Unfortunately, your brain will have been trained to ignore all comments by the 100 other completely useless comments that do nothing but add noise. If the tool generated that one comment without generating any useless comments, then it might be worth using.

shadowgovt 3y ago

I agree on that example. But contrast with this example: https://github.com/spring-projects/spring-boot/pull/39754/files#diff-23439aca4bd1fd8e9984f9739b011e128cd4b13f63dc3417786bc82d90ff41d7R70 https://github.com/spring-projects/spring-boot/pull/39754/fi... A function named `apply` with no documentation; you have to go up to the class to find the docs. And yes, it's not DRY to repeat the docs, but the fact the tool can pull relevant context into this location is helpful if it could be used as an on-the-fly doc generator (assuming, of course, it gives true output). People (understandably) don't want to repeat themselves but they also can't predict what entrypoint a reader enters their class from. I've definitely bounced off APIs before because something like `apply` isn't doc'd even though it's doc'd in source twenty lines away (because I'm busy; I'm not scanning entire source files on the off chance that the thing I'm looking for is nearby).

TheCoelacanth 3y ago
Unfortunately, your brain will have been trained to ignore all comments by the 100 other completely useless comments that do nothing but add noise. If the tool generated that one comment without generating any useless comments, then it might be worth using.