On Tue, 9 Apr 2024 23:19:53 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> Nizar Benalla has updated the pull request incrementally with one additional >> commit since the last revision: >> >> Update copyright year to 2024 > > [wangweij](https://github.com/wangweij) commented [3 weeks > ago](https://github.com/openjdk/jdk/pull/18373#issuecomment-2007161883) > I'd like to hear opinions from compiler experts. > > @wangweij you probably mean javadoc experts, not compiler experts ;-) > > The rules are currently quite simple, and can be expressed in effectively two > ways. Ignoring preview API and nested classes for now: > > 1. `javadoc` is very simple minded when it comes to handling `@since` tags -- > * if a `@since` tag is present in a documentation comment, it will > result in a `Since:` entry in the generated documentation. > * if there is no `@since` tag in the documentation comment, there will be > no `Since:` info in the generated documentation > > 2. Every declaration should have an `@since` tag indicating when it was first > introduced -- except for members of a class or interface if the `@since` > value would be the same as for the enclosing class or interface. > > * There are no special rules for inferring values for overriding methods. > * There are some special rules for Preview API outlines in [JEP > 12](https://openjdk.org/jeps/12) > * There is a PR in progress for `javadoc`, such that if a nested class or > interface has no `@since` tag of its own, the info from its enclosing class > or interface will be used to generate `Since:` info fir the generate API docs > for the nested class. @jonathan-gibbons Perhaps I was looking for a JSR export. To clarify, I don't have the authority to definitively say what the `@since` tag for an overridden method should represent. I'm here to listen to those who do have that authority. Maybe I should have removed the `security` label when I added `compiler`. ------------- PR Comment: https://git.openjdk.org/jdk/pull/18373#issuecomment-2046215624
