Quantcast

RFR: 8179915: Update extLink taglet to allow not linking the description

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

RFR: 8179915: Update extLink taglet to allow not linking the description

Kumar Srinivasan
Hi,

Please review fix for the custom taglet to allow openjdk builds, in
which case
the property "build.tools.taglet.ExtLink.NO_LINK" must be set to inhibit
server
side lookups.

Thanks
Kumar

Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

Erik Joelsson
Should this be set on the javadoc command line somewhere or am I missing
something?

/Erik


On 2017-05-10 09:42, Kumar Srinivasan wrote:

> Hi,
>
> Please review fix for the custom taglet to allow openjdk builds, in
> which case
> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
> inhibit server
> side lookups.
>
> Thanks
> Kumar
>
> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

Kumar Srinivasan

On 5/10/2017 9:51 AM, Erik Joelsson wrote:
> Should this be set on the javadoc command line somewhere or am I
> missing something?

Yes, one would have to set this prop, via the build system, when
performing a non-oracle build.

Kumar

>
> /Erik
>
>
> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>> Hi,
>>
>> Please review fix for the custom taglet to allow openjdk builds, in
>> which case
>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>> inhibit server
>> side lookups.
>>
>> Thanks
>> Kumar
>>
>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

David Holmes
On 11/05/2017 3:18 AM, Kumar Srinivasan wrote:
>
> On 5/10/2017 9:51 AM, Erik Joelsson wrote:
>> Should this be set on the javadoc command line somewhere or am I
>> missing something?
>
> Yes, one would have to set this prop, via the build system, when
> performing a non-oracle build.

Shouldn't that be inverted then - given there is only 1 Oracle build and
potentially innumerable non-Oracle builds? The default should be to not
link unless the property is set.

Thanks,
David

> Kumar
>
>>
>> /Erik
>>
>>
>> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>>> Hi,
>>>
>>> Please review fix for the custom taglet to allow openjdk builds, in
>>> which case
>>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>>> inhibit server
>>> side lookups.
>>>
>>> Thanks
>>> Kumar
>>>
>>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

roger riggs
In reply to this post by Kumar Srinivasan
Hi,

That's a pretty cryptic property, where will it be documented? Release
noted?

Is there any build option to set it so someone doesn't have to
circumvent the build system
to get the effect?

Thanks, Roger

On 5/10/2017 12:42 PM, Kumar Srinivasan wrote:

> Hi,
>
> Please review fix for the custom taglet to allow openjdk builds, in
> which case
> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
> inhibit server
> side lookups.
>
> Thanks
> Kumar
>
> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

Kumar Srinivasan

Hi Roger,

This is a build tool, ie. a tool used by the build system, potentially
could be documented in the build notes.

Kumar

> Hi,
>
> That's a pretty cryptic property, where will it be documented? Release
> noted?
>
> Is there any build option to set it so someone doesn't have to
> circumvent the build system
> to get the effect?
>
> Thanks, Roger
>
> On 5/10/2017 12:42 PM, Kumar Srinivasan wrote:
>> Hi,
>>
>> Please review fix for the custom taglet to allow openjdk builds, in
>> which case
>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>> inhibit server
>> side lookups.
>>
>> Thanks
>> Kumar
>>
>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

Kumar Srinivasan
In reply to this post by David Holmes
Hi,

Changes in this webrev:
* inverted the logic as you suggested
* some doc comment changes to reflect the change

http://cr.openjdk.java.net/~ksrini/8179915/webrev.1/

Thanks
Kumar

On 5/10/2017 7:19 PM, David Holmes wrote:

> On 11/05/2017 3:18 AM, Kumar Srinivasan wrote:
>>
>> On 5/10/2017 9:51 AM, Erik Joelsson wrote:
>>> Should this be set on the javadoc command line somewhere or am I
>>> missing something?
>>
>> Yes, one would have to set this prop, via the build system, when
>> performing a non-oracle build.
>
> Shouldn't that be inverted then - given there is only 1 Oracle build
> and potentially innumerable non-Oracle builds? The default should be
> to not link unless the property is set.
>
> Thanks,
> David
>
>> Kumar
>>
>>>
>>> /Erik
>>>
>>>
>>> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>>>> Hi,
>>>>
>>>> Please review fix for the custom taglet to allow openjdk builds, in
>>>> which case
>>>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>>>> inhibit server
>>>> side lookups.
>>>>
>>>> Thanks
>>>> Kumar
>>>>
>>>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>>>
>>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

roger riggs
Hi,

I would generalize it just a bit by taking the URL from the system property;
if the property was set it would use the URL and if not generate the
citation.
Then the taglet could be used a bit more broadly without complicating
the build or code.

$.02, Roger


On 5/11/2017 4:51 PM, Kumar Srinivasan wrote:

> Hi,
>
> Changes in this webrev:
> * inverted the logic as you suggested
> * some doc comment changes to reflect the change
>
> http://cr.openjdk.java.net/~ksrini/8179915/webrev.1/
>
> Thanks
> Kumar
>
> On 5/10/2017 7:19 PM, David Holmes wrote:
>> On 11/05/2017 3:18 AM, Kumar Srinivasan wrote:
>>>
>>> On 5/10/2017 9:51 AM, Erik Joelsson wrote:
>>>> Should this be set on the javadoc command line somewhere or am I
>>>> missing something?
>>>
>>> Yes, one would have to set this prop, via the build system, when
>>> performing a non-oracle build.
>>
>> Shouldn't that be inverted then - given there is only 1 Oracle build
>> and potentially innumerable non-Oracle builds? The default should be
>> to not link unless the property is set.
>>
>> Thanks,
>> David
>>
>>> Kumar
>>>
>>>>
>>>> /Erik
>>>>
>>>>
>>>> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>>>>> Hi,
>>>>>
>>>>> Please review fix for the custom taglet to allow openjdk builds, in
>>>>> which case
>>>>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>>>>> inhibit server
>>>>> side lookups.
>>>>>
>>>>> Thanks
>>>>> Kumar
>>>>>
>>>>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>>>>
>>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

Jonathan Gibbons
Roger,

We discussed this in the original design.  This is a JDK-specific
taglet, for use in the JDK-build,
for building JDK API-specifications, that may or may not link to some
commercial documentation.

There is no intent to support {@extLink} for anything outside its
limited use in the JDK API
documentation. The whole mechanism of using a query URL like this, and
the set of names
that is defined, is highly specific to this one usage.

Given this limited usage, is it really helpful to generalize it so that
we move the base URL from
one place in the JDK build infrastructure to another?

We seem to be in a bikeshed.

-- Jon

On 05/11/2017 02:07 PM, Roger Riggs wrote:

> Hi,
>
> I would generalize it just a bit by taking the URL from the system
> property;
> if the property was set it would use the URL and if not generate the
> citation.
> Then the taglet could be used a bit more broadly without complicating
> the build or code.
>
> $.02, Roger
>
>
> On 5/11/2017 4:51 PM, Kumar Srinivasan wrote:
>> Hi,
>>
>> Changes in this webrev:
>> * inverted the logic as you suggested
>> * some doc comment changes to reflect the change
>>
>> http://cr.openjdk.java.net/~ksrini/8179915/webrev.1/
>>
>> Thanks
>> Kumar
>>
>> On 5/10/2017 7:19 PM, David Holmes wrote:
>>> On 11/05/2017 3:18 AM, Kumar Srinivasan wrote:
>>>>
>>>> On 5/10/2017 9:51 AM, Erik Joelsson wrote:
>>>>> Should this be set on the javadoc command line somewhere or am I
>>>>> missing something?
>>>>
>>>> Yes, one would have to set this prop, via the build system, when
>>>> performing a non-oracle build.
>>>
>>> Shouldn't that be inverted then - given there is only 1 Oracle build
>>> and potentially innumerable non-Oracle builds? The default should be
>>> to not link unless the property is set.
>>>
>>> Thanks,
>>> David
>>>
>>>> Kumar
>>>>
>>>>>
>>>>> /Erik
>>>>>
>>>>>
>>>>> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>>>>>> Hi,
>>>>>>
>>>>>> Please review fix for the custom taglet to allow openjdk builds, in
>>>>>> which case
>>>>>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>>>>>> inhibit server
>>>>>> side lookups.
>>>>>>
>>>>>> Thanks
>>>>>> Kumar
>>>>>>
>>>>>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>>>>>
>>>>
>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

Magnus Ihse Bursie
In reply to this post by Kumar Srinivasan
Kumar,

This was not an improvement. This will require additional changes in the build system to avoid a regression. I see no reason for that.

In fact, I propose we close the bug as WNF. Let me elaborate.

The problem here is that Oracle has dual roles: partly as a contributor to OpenJDK, and partly as a independent company that wants to contribute to the Java ecosystem outside of the OpenJDK project.

To Oracle's credit, most of the documentation provided goes into the OpenJDK project (and repositories). For some reason or reasons, Oracle chose to not so so with all Java-related documentation, typically user guides etc.

The crucial question is then: should the OpenJDK documentation point to the (proprietary) Oracle documentation?

From the OpenJDK perspective, the ideal would be if the documentation was included with the OpenJDK distribution, but if that is not going to happen, then what is the best for the project?

I would argue that it is still better to link to the Oracle documents than to not do it. We have no qualms linking to other third party sites where suitable and helpful to the reader, and this is no different.

(Yes, I have changed my opinion about this.)

This is not a question about what the Oracle JDK will do, since it will definitely link to the Oracle guides no matter what. What I'm thinking of is if the OpenJDK in any way would be considered helped by *not* linking to publicly available documentation on Oracle's web site. I can't see any such reason, and therefore, I see no reason not to link, making this addition unnecessary.

That said, I hope that in due time, Oracle will consider adding more of the documentation to the OpenJDK project, if it seems reasonable that it belongs here.

/Magnus

> 11 maj 2017 kl. 22:51 skrev Kumar Srinivasan <[hidden email]>:
>
> Hi,
>
> Changes in this webrev:
> * inverted the logic as you suggested
> * some doc comment changes to reflect the change
>
> http://cr.openjdk.java.net/~ksrini/8179915/webrev.1/
>
> Thanks
> Kumar
>
>> On 5/10/2017 7:19 PM, David Holmes wrote:
>>> On 11/05/2017 3:18 AM, Kumar Srinivasan wrote:
>>>
>>>> On 5/10/2017 9:51 AM, Erik Joelsson wrote:
>>>> Should this be set on the javadoc command line somewhere or am I
>>>> missing something?
>>>
>>> Yes, one would have to set this prop, via the build system, when
>>> performing a non-oracle build.
>>
>> Shouldn't that be inverted then - given there is only 1 Oracle build and potentially innumerable non-Oracle builds? The default should be to not link unless the property is set.
>>
>> Thanks,
>> David
>>
>>> Kumar
>>>
>>>>
>>>> /Erik
>>>>
>>>>
>>>>> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>>>>> Hi,
>>>>>
>>>>> Please review fix for the custom taglet to allow openjdk builds, in
>>>>> which case
>>>>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>>>>> inhibit server
>>>>> side lookups.
>>>>>
>>>>> Thanks
>>>>> Kumar
>>>>>
>>>>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

Jonathan Gibbons
Magnus,

I agree with this, and agree with closing it WNF.

-- Jon

On 05/12/2017 12:16 AM, Magnus Ihse Bursie wrote:

> Kumar,
>
> This was not an improvement. This will require additional changes in the build system to avoid a regression. I see no reason for that.
>
> In fact, I propose we close the bug as WNF. Let me elaborate.
>
> The problem here is that Oracle has dual roles: partly as a contributor to OpenJDK, and partly as a independent company that wants to contribute to the Java ecosystem outside of the OpenJDK project.
>
> To Oracle's credit, most of the documentation provided goes into the OpenJDK project (and repositories). For some reason or reasons, Oracle chose to not so so with all Java-related documentation, typically user guides etc.
>
> The crucial question is then: should the OpenJDK documentation point to the (proprietary) Oracle documentation?
>
>  From the OpenJDK perspective, the ideal would be if the documentation was included with the OpenJDK distribution, but if that is not going to happen, then what is the best for the project?
>
> I would argue that it is still better to link to the Oracle documents than to not do it. We have no qualms linking to other third party sites where suitable and helpful to the reader, and this is no different.
>
> (Yes, I have changed my opinion about this.)
>
> This is not a question about what the Oracle JDK will do, since it will definitely link to the Oracle guides no matter what. What I'm thinking of is if the OpenJDK in any way would be considered helped by *not* linking to publicly available documentation on Oracle's web site. I can't see any such reason, and therefore, I see no reason not to link, making this addition unnecessary.
>
> That said, I hope that in due time, Oracle will consider adding more of the documentation to the OpenJDK project, if it seems reasonable that it belongs here.
>
> /Magnus
>
>> 11 maj 2017 kl. 22:51 skrev Kumar Srinivasan <[hidden email]>:
>>
>> Hi,
>>
>> Changes in this webrev:
>> * inverted the logic as you suggested
>> * some doc comment changes to reflect the change
>>
>> http://cr.openjdk.java.net/~ksrini/8179915/webrev.1/
>>
>> Thanks
>> Kumar
>>
>>> On 5/10/2017 7:19 PM, David Holmes wrote:
>>>> On 11/05/2017 3:18 AM, Kumar Srinivasan wrote:
>>>>
>>>>> On 5/10/2017 9:51 AM, Erik Joelsson wrote:
>>>>> Should this be set on the javadoc command line somewhere or am I
>>>>> missing something?
>>>> Yes, one would have to set this prop, via the build system, when
>>>> performing a non-oracle build.
>>> Shouldn't that be inverted then - given there is only 1 Oracle build and potentially innumerable non-Oracle builds? The default should be to not link unless the property is set.
>>>
>>> Thanks,
>>> David
>>>
>>>> Kumar
>>>>
>>>>> /Erik
>>>>>
>>>>>
>>>>>> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>>>>>> Hi,
>>>>>>
>>>>>> Please review fix for the custom taglet to allow openjdk builds, in
>>>>>> which case
>>>>>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>>>>>> inhibit server
>>>>>> side lookups.
>>>>>>
>>>>>> Thanks
>>>>>> Kumar
>>>>>>
>>>>>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: 8179915: Update extLink taglet to allow not linking the description

David Holmes
In reply to this post by Magnus Ihse Bursie
On 12/05/2017 5:16 PM, Magnus Ihse Bursie wrote:

> Kumar,
>
> This was not an improvement. This will require additional changes in the build system to avoid a regression. I see no reason for that.
>
> In fact, I propose we close the bug as WNF. Let me elaborate.
>
> The problem here is that Oracle has dual roles: partly as a contributor to OpenJDK, and partly as a independent company that wants to contribute to the Java ecosystem outside of the OpenJDK project.
>
> To Oracle's credit, most of the documentation provided goes into the OpenJDK project (and repositories). For some reason or reasons, Oracle chose to not so so with all Java-related documentation, typically user guides etc.
>
> The crucial question is then: should the OpenJDK documentation point to the (proprietary) Oracle documentation?
>
> From the OpenJDK perspective, the ideal would be if the documentation was included with the OpenJDK distribution, but if that is not going to happen, then what is the best for the project?
>
> I would argue that it is still better to link to the Oracle documents than to not do it. We have no qualms linking to other third party sites where suitable and helpful to the reader, and this is no different.
>
> (Yes, I have changed my opinion about this.)
>
> This is not a question about what the Oracle JDK will do, since it will definitely link to the Oracle guides no matter what. What I'm thinking of is if the OpenJDK in any way would be considered helped by *not* linking to publicly available documentation on Oracle's web site. I can't see any such reason, and therefore, I see no reason not to link, making this addition unnecessary.

Not knowing exactly where this proprietary Oracle documentation will end
up, I can't say whether it will be truly publicly available or whether
you will have to log on to the "technical network" to access it?

That aside IIUC the issue/concern is that other members of the OpenJDK
community may want to produce documentation bundles that do not contain
links to external sites such as Oracle's.

This is a policy decision that should not be being made by the engineers
on the front-line so to speak.

David
-----

> That said, I hope that in due time, Oracle will consider adding more of the documentation to the OpenJDK project, if it seems reasonable that it belongs here.
>
> /Magnus
>
>> 11 maj 2017 kl. 22:51 skrev Kumar Srinivasan <[hidden email]>:
>>
>> Hi,
>>
>> Changes in this webrev:
>> * inverted the logic as you suggested
>> * some doc comment changes to reflect the change
>>
>> http://cr.openjdk.java.net/~ksrini/8179915/webrev.1/
>>
>> Thanks
>> Kumar
>>
>>> On 5/10/2017 7:19 PM, David Holmes wrote:
>>>> On 11/05/2017 3:18 AM, Kumar Srinivasan wrote:
>>>>
>>>>> On 5/10/2017 9:51 AM, Erik Joelsson wrote:
>>>>> Should this be set on the javadoc command line somewhere or am I
>>>>> missing something?
>>>>
>>>> Yes, one would have to set this prop, via the build system, when
>>>> performing a non-oracle build.
>>>
>>> Shouldn't that be inverted then - given there is only 1 Oracle build and potentially innumerable non-Oracle builds? The default should be to not link unless the property is set.
>>>
>>> Thanks,
>>> David
>>>
>>>> Kumar
>>>>
>>>>>
>>>>> /Erik
>>>>>
>>>>>
>>>>>> On 2017-05-10 09:42, Kumar Srinivasan wrote:
>>>>>> Hi,
>>>>>>
>>>>>> Please review fix for the custom taglet to allow openjdk builds, in
>>>>>> which case
>>>>>> the property "build.tools.taglet.ExtLink.NO_LINK" must be set to
>>>>>> inhibit server
>>>>>> side lookups.
>>>>>>
>>>>>> Thanks
>>>>>> Kumar
>>>>>>
>>>>>> Webrev: http://cr.openjdk.java.net/~ksrini/8179915/webrev.0
>>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8179915
>>
>
Loading...