FYI: new javadoc tag to document system properties

[Jonathan Gibbons]

By itself, {@index} does not generate top-level summary pages; it has 
not hitherto been suggested that it could/should.

You can define your own Taglet, although this is typically for 
relatively simple tags. I don't know that we have enough hooks in the 
API for a user-defined taglet to put info into the index. It would be a 
good goal/enhancement to allow that.

{@index} was added in JDK 9, as part of the work for the "Javadoc 
Search" feature.

-- Jon


On 11/15/2018 09:36 AM, Bill Shannon wrote:
> And that will group all those properties together on a summary page 
> under "JavaMail session property"?  And it will generate the same sort 
> of html anchor for the property?
>
> Ok, that would be fine.
>
> Too bad we don't have macros so I could define my own 
> "@JavaMailProperty" tag.  :-)
>
> Is @index something new in JDK 12?
>
>
> Jonathan Gibbons wrote on 11/15/18 9:28 AM:
>>
>> Bill,
>>
>> The intent is that this feature is just for system properties. In 
>> upcoming releases, we expect to extend the feature to provide a 
>> top-level summary page listing all the system properties.
>>
>> For other kinds of properties, such as the JavaMail session 
>> properties, you can use
>>
>>     {@index property-name short-description}
>>
>> such as
>>     {@index mail.smtp.user JavaMail session property}
>>
>> -- Jon
>>
>>
>> On 11/14/2018 10:58 PM, Bill Shannon wrote:
>>> Could we just call them "Properties" ib the index, to allow this new 
>>> feature to be more widely used?
>>>
>>> Priya Lakshmi Muthuswamy wrote on 11/14/18 9:43 PM:
>>>>
>>>> When a property-name is wrapped with {@systemProperty propertyname} 
>>>> tag, the search Index and A-Z index will have
>>>> short description mentioning it as system property.
>>>>
>>>> In the defining page, the property name will be wrapped within a 
>>>> html anchor and index entry will point to this.
>>>> /java.base/java/lang/System.html#java.version.
>>>>
>>>> Thanks,
>>>> Priya
>>>> On 11/15/2018 9:45 AM, Bill Shannon wrote:
>>>>> JavaMail defines a bunch of System properties as well as JavaMail Session
>>>>> properties.  For example:
>>>>> https://javaee.github.io/javamail/docs/api/javax/mail/internet/package-summary.html#package.description
>>>>>
>>>>> Would this tag be usable for both?
>>>>>
>>>>> Would there be any reason to distinguish between System properties and
>>>>> Session properties when using this tag?  If it's just adding an entry to
>>>>> the index that links back to the defining page, that distinction doesn't
>>>>> seem necessary.
>>>>>
>>>>> The defining entries in the page above use html anchors, e.g.,
>>>>> https://javaee.github.io/javamail/docs/api/javax/mail/internet/package-summary.html#mail.mime.charset
>>>>> Is there a way to cause the tag to generate an index entry that uses
>>>>> the anchor, or does it just link to the defining page?
>>>>>
>>>>>
>>>>> Jonathan Gibbons wrote on 11/14/18 2:27 PM:
>>>>>> This is an FYI to announce some initial, long-overdue support in javadoc for
>>>>>> documenting system properties (JDK-5076751).
>>>>>>
>>>>>> Currently, system properties are just documented using ad-hoc narrative text,
>>>>>> which is fine if you know where to look for any given property.
>>>>>>
>>>>>> JDK 12 introduces a new inline javadoc tag, {@systemProperty /property-name/}
>>>>>> which can be used to "declare" the name of a system property. You can use this
>>>>>> tag as a drop-in replacement for the plain-text property name; it will have no
>>>>>> overt effect on the narrative text, but it will cause the property name to be
>>>>>> put into the search index and the A-Z index. Thus, property names will become
>>>>>> searchable, to allow users to easily find the definition of any such system
>>>>>> property.
>>>>>>
>>>>>> Adding support into javadoc is only part of the story. Now that the support is
>>>>>> in javadoc, we want to update the API documentation, so that the documentation
>>>>>> is updated for all Java SE and JDK system properties.
>>>>>>
>>>>>> Where should the tag be used?  The tag should be used in the text of the
>>>>>> defining instance of the property.  This is where the characteristics of the
>>>>>> system property are described, which may include information like: "what is the
>>>>>> property for", "how and when is it set", "can it be modified", and so on. For
>>>>>> example, it could be used in the docs for System.getProperties [1] or Networking
>>>>>> Properties [2] In general, it should -not- be used in situations that merely
>>>>>> refer to the system property by name.  For example, the docs for
>>>>>> Path.toAbsolutePath [3] make a reference to the system property user.dir, but
>>>>>> that is not a definition of the property.
>>>>>>
>>>>>> Going forward, in future releases, we expect to explore some enhancements to
>>>>>> this feature. Here are some of the ideas that have been suggested:
>>>>>>
>>>>>>   * Create a "summary page" that lists all the system properties. This
>>>>>>     would be somewhat similar to the current top-level "Constant Values"
>>>>>>     page.
>>>>>>   * Add information regarding the "scope" of the definition: is it
>>>>>>     defined by the Java SE specification, or JDK, or JavaFX, etc. This
>>>>>>     information could be used to organize the content on the summary page.
>>>>>>   * Update @see and {@link} to be able to refer to system properties.
>>>>>>   * Allow a short description to be included in the {@systemProperty}
>>>>>>     tag. This text could be included in the search index, the A-Z index,
>>>>>>     and the summary page.
>>>>>>
>>>>>> -- Jon
>>>>>>
>>>>>>
>>>>>> [1]:
>>>>>> https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/System.html#getProperties()
>>>>>>
>>>>>> [2]:
>>>>>> https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/doc-files/net-properties.html
>>>>>>
>>>>>> [3]:
>>>>>> https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Path.html#toAbsolutePath()
>>>>>>
>>>>>>
>>>>>>
>>>
>>
>