Re: FYI: new javadoc tag to document system properties
Roger,
In general, and without looking at the JCE API, I note that
module-info.java is where providers are declared (i.e. the provides
directive and @provides tag.) So this might indeed be a reasonable place
to document information relevant to the provider, such as any properties
it might support.
A different way to phrase your comment would be to suggest putting the
info about system properties in the smallest enclosing publicly
documented element (module, package, type, etc). Sometimes, especially
with provider modules, the module-info.java is the only place to put the
information.
-- Jon
On 11/16/2018 06:49 AM, Roger Riggs wrote:
Hi,
module-info.java isn't a good place; its too far from the relevant API
that it affects.
The property should be documented where it make sense and where
developers
will find it.
In this case, since it is provider specific, it makes sense to define
the property
where the provider is described or documented. If the provider is not
defined anywhere,
then its all implementation and probably should *not* be documented.
Roger
On 11/15/2018 10:42 PM, Weijun Wang wrote:
I had also thought about this. In JCE, the API and implementation
(aka provider) might even be in different modules, if some system
properties only apply a specific provider, we can put them into
module-info.java of that module.
We do support the new tag in module-info.java, right?
Thanks
Max
On Nov 16, 2018, at 12:31 AM, Roger Riggs
wrote:
Hi,
If a system property is defined and specified as supported then it
needs a public declaration and specification as part of the public
class or package documentation.
Checking for and adding the tag will be a good way to reconfirm
property definitions are in the right place.
Would it be reasonable to use only core-libs-dev for any remaining
discussion?
Seeing it on 5 aliases doesn't seem productive.
$.02, Roger
On 11/15/2018 11:17 AM, Xuelei Fan wrote:
In JCE and JSSE, the public APIs definition (javax.net.ssl) and the
internal implementation (sun.security.ssl) are separated. The
system property can be defined in the internal implementation
classes. I think we should add the @systemProperty on the public
APIs, right?
The public API class and the implementation class may be not a
one-to-one map. Multiple public APIs may be impacted by the system
property. How to handle such cases?
Thanks,
Xuelei
On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
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]:
Re: FYI: new javadoc tag to document system properties
Hi,
module-info.java isn't a good place; its too far from the relevant API
that it affects.
The property should be documented where it make sense and where developers
will find it.
In this case, since it is provider specific, it makes sense to define
the property
where the provider is described or documented. If the provider is not
defined anywhere,
then its all implementation and probably should *not* be documented.
Roger
On 11/15/2018 10:42 PM, Weijun Wang wrote:
I had also thought about this. In JCE, the API and implementation (aka
provider) might even be in different modules, if some system properties only
apply a specific provider, we can put them into module-info.java of that module.
We do support the new tag in module-info.java, right?
Thanks
Max
On Nov 16, 2018, at 12:31 AM, Roger Riggs wrote:
Hi,
If a system property is defined and specified as supported then it needs a
public declaration and specification as part of the public class or package
documentation.
Checking for and adding the tag will be a good way to reconfirm property
definitions are in the right place.
Would it be reasonable to use only core-libs-dev for any remaining discussion?
Seeing it on 5 aliases doesn't seem productive.
$.02, Roger
On 11/15/2018 11:17 AM, Xuelei Fan wrote:
In JCE and JSSE, the public APIs definition (javax.net.ssl) and the internal
implementation (sun.security.ssl) are separated. The system property can be
defined in the internal implementation classes. I think we should add the
@systemProperty on the public APIs, right?
The public API class and the implementation class may be not a one-to-one map.
Multiple public APIs may be impacted by the system property. How to handle
such cases?
Thanks,
Xuelei
On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
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()
Re: FYI: new javadoc tag to document system properties
I had also thought about this. In JCE, the API and implementation (aka
provider) might even be in different modules, if some system properties only
apply a specific provider, we can put them into module-info.java of that module.
We do support the new tag in module-info.java, right?
Thanks
Max
> On Nov 16, 2018, at 12:31 AM, Roger Riggs wrote:
>
> Hi,
>
> If a system property is defined and specified as supported then it needs a
> public declaration and specification as part of the public class or package
> documentation.
> Checking for and adding the tag will be a good way to reconfirm property
> definitions are in the right place.
>
> Would it be reasonable to use only core-libs-dev for any remaining discussion?
> Seeing it on 5 aliases doesn't seem productive.
>
> $.02, Roger
>
>
> On 11/15/2018 11:17 AM, Xuelei Fan wrote:
>> In JCE and JSSE, the public APIs definition (javax.net.ssl) and the internal
>> implementation (sun.security.ssl) are separated. The system property can be
>> defined in the internal implementation classes. I think we should add the
>> @systemProperty on the public APIs, right?
>>
>> The public API class and the implementation class may be not a one-to-one
>> map. Multiple public APIs may be impacted by the system property. How to
>> handle such cases?
>>
>> Thanks,
>> Xuelei
>>
>> On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
>>> 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()
>>>
>>>
>>>
>
Re: FYI: new javadoc tag to document system properties
Hi,
If a system property is defined and specified as supported then it needs
a public declaration and specification as part of the public class or
package documentation.
Checking for and adding the tag will be a good way to reconfirm property
definitions are in the right place.
Would it be reasonable to use only core-libs-dev for any remaining
discussion?
Seeing it on 5 aliases doesn't seem productive.
$.02, Roger
On 11/15/2018 11:17 AM, Xuelei Fan wrote:
In JCE and JSSE, the public APIs definition (javax.net.ssl) and the
internal implementation (sun.security.ssl) are separated. The system
property can be defined in the internal implementation classes. I
think we should add the @systemProperty on the public APIs, right?
The public API class and the implementation class may be not a
one-to-one map. Multiple public APIs may be impacted by the system
property. How to handle such cases?
Thanks,
Xuelei
On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
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()
Re: FYI: new javadoc tag to document system properties
In JCE and JSSE, the public APIs definition (javax.net.ssl) and the
internal implementation (sun.security.ssl) are separated. The system
property can be defined in the internal implementation classes. I think
we should add the @systemProperty on the public APIs, right?
The public API class and the implementation class may be not a
one-to-one map. Multiple public APIs may be impacted by the system
property. How to handle such cases?
Thanks,
Xuelei
On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
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()
Re: FYI: new javadoc tag to document system properties
Hello,
For future CSR requests involving system properties, please document the
properties using these javadoc facilities.
Thanks,
-Joe
On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
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()
FYI: new javadoc tag to document system properties
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()
