Add overridden method javadoc if none exists on declared method

[Sheikah45]

This adds javadoc from the overridden method in super class or interfaces if none is present on the declared method during the annotation processing phase. When a class is extended and/or multiple interfaces are implemented with the same signature priority returned by Types.directSuperTypes as is done by the javadoc command line tool The super elements are depth first searched for overrding method javadoc and the first found javadoc is returned. Note this implementation does not require @ Override to be present on the method.

Note that since this performs the javadoc copying during the annotation processing there is potentially duplication of javadoc. Also this does not support the partial inheritance of javadoc parts as described at https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#inheritingcomments.

I chose this method to try and limit the edge cases that pop up with determining overrides in the reflection API especially when it comes to generics, type erasure, and bridge methods. That being said an implementation of finding the overriding method at runtime could be done as a complement to this or a wholesale replacement depending on the value of minimizing any tree traversal at runtime.

Let me know if you want any changes, see any holes or think the runtime approach is better.

This did not cover the case of adding the javadoc from protected fields or parsing @ inheritdoc as I think these are a separate concern.

Note that when you generate javadoc for the VeryComplexImplementation it actually does not follow the algorithm provided in the link. It actually performs recursive search on the superclass first resulting in inheriting the javadoc for the fling method from DocumentedInterface rather than CompetingInterface as would be expected if the algorithm ran as described. So likely the order priority is something that changes with java versions unfortunately

Closes #61

[dnault]

Hi @Sheikah45. First of all, thank you for this PR!

Let me know if you want any changes, see any holes or think the runtime approach is better.

A runtime approach would have the advantage of handling cases where the superclass and subclass are compiled separately. For example, they could be in different jars, and the superclass Javadoc could still be located at runtime.

I chose this method to try and limit the edge cases that pop up with determining overrides in the reflection API especially when it comes to generics, type erasure, and bridge methods.

Spring has a BridgeMethodResolver we might be able to borrow. Both projects use Apache 2.0 license -- we'd just need to document where the code came from.

https://github.com/spring-projects/spring-framework/blob/main/spring-core/src/main/java/org/springframework/core/BridgeMethodResolver.java

Do you think that's worth exploring?

[Sheikah45]

Yes that could be helpful although we would likely want to invert it so that we could find the bridged method from the original method so that we could traverse the hierarchy. I can take a look at implementing it. I actually implemented something similar in the code I use this for however there I can make assumptions on some of the relationships that I can't necessarily do in the general case.

What are your thoughts on whether it should be just runtime or if compile resolution should be included as well?

Also what are your thoughts on reading missing parts from the overriding method?

[dnault]

What are your thoughts on whether it should be just runtime or if compile resolution should be included as well?

A pure runtime solution would be ideal. It will be good if the new version of the runtime library is compatible with JSON generated by the previous version of the annotation processor.

Also what are your thoughts on reading missing parts from the overriding method?

The ultimate goal is to do the same thing as Java 17's Standard Doclet (see the "Comment Inheritance" section).

It feels to me like this will be significantly easier to do at runtime. I haven't thought too much about the details, though.

[Sheikah45]

Sounds good, I should have the runtime pr open in a second. Although I still haven't seen the javadoc tool shipped with the jdk actually follow the algorithm for inheritance as listed there. Have you found that it checks interfaces before classes?

[Sheikah45]

A pure runtime solution would be ideal. It will be good if the new version of the runtime library is compatible with JSON generated by the previous version of the annotation processor.

And yeah there is no reason to modify the json format

[Sheikah45]

Superceded by #64