Add @see to bean suppression methods' javadoc to link them together #40716
Conversation
sixcorners
changed the title
| @@ -53,6 +55,9 @@ | |||
| * </pre> | |||
| * | |||
| * @see Instance | |||
| * @see LookupUnlessProperty | |||
There was a problem hiding this comment.
Yeah, agree. @IfBuildProperty and @LookupIfProperty look superficially similar, but they are very different (the first is build-time only, the other is runtime-aware but only applies to dynamic lookup). I wouldn't add a @see reference to them.
There was a problem hiding this comment.
Agreed, LookupIfProperty and LookupUnlessProperty should reference each other a so should IfBuildProperty/UnlessBuildProperty but I wouldn't cross reference them.
There was a problem hiding this comment.
Would it make sense to change it to a sentence that links them together but also states the difference? I kind of feel like someone looking for one might end up looking at the docs for the other.
There was a problem hiding this comment.
Both of these concepts are explained within the same document - https://quarkus.io/guides/cdi-reference
To me the difference is clear enough there but I am definitely biased as I am familiar with CDI as well as and many of these concepts. If you feel like you can add a sensible comparison there, it might be better than the javadoc?
There was a problem hiding this comment.
I know they are explained on the website but putting the information in the javadoc can help when you are just asking your IDE to bring up the annotation name you kind of remember and you wind up at the wrong one.
see doesn't mean that the linked thing does the same thing. NormalScope for instance references Scope despite them working differently. When I look at the javadoc of something and it points at something that sounds the same my assumption would be the opposite of thinking they work the same way.
There was a problem hiding this comment.
Hm, the problem is that those annotations not only "work differently", they are used in different phases of the app lifecycle. IfBuildProperty is considered at build time whereas the LookupIfProperty is used during programmatic lookup at runtime. So I think that a simple @see reference does not really help but instead can be confusing for users.
I think that we should either add a paragraph like "If you need to control the enablement of a bean at build time then use..." or skip the build time annotations completely.
Think this is a good idea?