On Fri, 31 May 2024 20:58:31 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
> > To clarify, I'm not too concerned with how we call an action whereby a > > nested class gets its `@since` tag from the enclosing class; but yes, > > "inheritance" might not be ideal. What I'm concerned with is the fact that > > the logic originally provided in > > [`getDefaultBlockTags`](https://github.com/openjdk/jdk/blob/6ee8407758c92d32e18642b0758d2d5c71ad09f5/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SimpleTaglet.java#L141-L147) > > is now duplicated in `getInheritedDocTreePath`. > > Like I said, while it's bad, the new duplication merely replicates the one > > we already have between `InheritableTaglet.inherit` and > > `getInheritedDocTreePath`. > > If we can't fix this in the next few days, we should file a cleanup issue to > resolve this duplication. I don't quite see the problem with this, or how to improve it substantially (beyond finding better terminology). We have different ways of obtaining doc comment fragments from related elements. The major and well-established one is along the lines of Java type inheritance, and a minor/new one along enclosing/enclosed classes. Since `CommentHelper` provides a means to reverse lookup `DocTree` -> `DocTreePath`, it necessarily needs to know about all of these mechanisms. The code for the enclosing/enclosed classes is actually trivial, so I don't see how this could be simplified further. The code for finding doc comments along type inheritance is more complex, but it already delegates to the `DocFinder` class, which is also used for the primary lookup for inherited doc comments. I certainly don't think the existing/proposed code is perfect, but I don't see huge potential for improvement. Of course I'm open to learn and better understand the issues, and how to solve them. ------------- PR Comment: https://git.openjdk.org/jdk/pull/19363#issuecomment-2145104410
