FYI: new javadoc tag to document system properties

[Bill Shannon]

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()
>>>>>
>>>>>
>>>>>
>>
>