RFR: JDK-8328501 Incorrect @since` tags for java security interfaces [v3]

[Weijun Wang]

On Tue, 9 Apr 2024 23:19:53 GMT, Jonathan Gibbons <jjg at 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