Please review: JDK-8178725: provide way to link to external documentation

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

Please review: JDK-8178725: provide way to link to external documentation

Kumar Srinivasan
Hello,

As explained in the JBS issue [1], this new taglet enables API documents
to contain the extLink tag to link external sources.

Please review the webrev [2].

Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8178725
[2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Please review: JDK-8178725: provide way to link to external documentation

Erik Joelsson
The build change looks ok to me, but Magnus should definitely look at
this since he is so heavily involved in the Javadoc build right now.

/Erik


On 2017-04-18 19:44, Kumar Srinivasan wrote:

> Hello,
>
> As explained in the JBS issue [1], this new taglet enables API documents
> to contain the extLink tag to link external sources.
>
> Please review the webrev [2].
>
> Thanks
> Kumar
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Kumar Srinivasan

Thanks Erik, yes will wait for Magnus' and Jon's comments.

Kumar

> The build change looks ok to me, but Magnus should definitely look at
> this since he is so heavily involved in the Javadoc build right now.
>
> /Erik
>
>
> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>> Hello,
>>
>> As explained in the JBS issue [1], this new taglet enables API documents
>> to contain the extLink tag to link external sources.
>>
>> Please review the webrev [2].
>>
>> Thanks
>> Kumar
>>
>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Jonathan Gibbons
The use of double quotes in the example might lead one to incorrectly
believe that they are required.

The example should work without the quotes:

   43 /**
   44  * An inline tag to conveniently insert an external link.
   45  * The tag can be used as follows:
   46  * {@extLink name description}, for example
   47  * <p>
   48  * {@code
   49  *     Please see {@extLink Borealis a spectacular} sight.
   50  * }
   51  * <p>
   52  * will produce the following html
   53  * <p>
   54  * {@code
   55  *     Please see <a href="https://www.oracle.com/pls/topic/lookup?ctx=javase9&id=Borealis">a spectacular</a> sight.
   56  * }
   57  * }
   58  */


The indentation in both the comment and the source code is a bit
inconsistent. Is that an extra } on line 57?

The regex will fail if there are too many spaces between "{@extLink" and
the name.   [1]

-- Jon


[1]:
https://blog.codinghorror.com/regular-expressions-now-you-have-two-problems/


On 04/18/2017 11:26 AM, Kumar Srinivasan wrote:

>
> Thanks Erik, yes will wait for Magnus' and Jon's comments.
>
> Kumar
>
>> The build change looks ok to me, but Magnus should definitely look at
>> this since he is so heavily involved in the Javadoc build right now.
>>
>> /Erik
>>
>>
>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>> Hello,
>>>
>>> As explained in the JBS issue [1], this new taglet enables API
>>> documents
>>> to contain the extLink tag to link external sources.
>>>
>>> Please review the webrev [2].
>>>
>>> Thanks
>>> Kumar
>>>
>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Magnus Ihse Bursie
In reply to this post by Kumar Srinivasan
On 2017-04-18 19:44, Kumar Srinivasan wrote:
> Hello,
>
> As explained in the JBS issue [1], this new taglet enables API documents
> to contain the extLink tag to link external sources.
>
> Please review the webrev [2].
Changes looks good.

Just a reflection: This is heavily biased to Oracle documentation. Even
if it's possible to override the URL via a system property, it assumes
the Oracle URL format and id name. Just wondering a bit how that fits
with the OpenJDK philosophy.

/Magnus

>
> Thanks
> Kumar
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

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

Re: Please review: JDK-8178725: provide way to link to external documentation

David Holmes
On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:

> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>> Hello,
>>
>> As explained in the JBS issue [1], this new taglet enables API documents
>> to contain the extLink tag to link external sources.
>>
>> Please review the webrev [2].
> Changes looks good.
>
> Just a reflection: This is heavily biased to Oracle documentation. Even
> if it's possible to override the URL via a system property, it assumes
> the Oracle URL format and id name. Just wondering a bit how that fits
> with the OpenJDK philosophy.

I have to agree, this is not at all general purpose but totally Oracle
documentation centric.

David
-----


> /Magnus
>
>>
>> Thanks
>> Kumar
>>
>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Please review: JDK-8178725: provide way to link to external documentation

Kumar Srinivasan
In reply to this post by Jonathan Gibbons
Have made the following changes:
* fixed the indentations, basically pointed the IDE and asked it to
    reformat the whole file
* fixed regex, to be defensive against leading WS, though the
DocCommentParser
    whacks the WS.

Please see updated webrev:
http://cr.openjdk.java.net/~ksrini/8178725/webrev.01/

Thanks
Kumar


On 4/18/2017 3:27 PM, Jonathan Gibbons wrote:

> The use of double quotes in the example might lead one to incorrectly
> believe that they are required.
>
> The example should work without the quotes:
>
>   43 /**
>   44  * An inline tag to conveniently insert an external link.
>   45  * The tag can be used as follows:
>   46  * {@extLink name description}, for example
>   47  * <p>
>   48  * {@code
>   49  *     Please see {@extLink Borealis a spectacular} sight.
>   50  * }
>   51  * <p>
>   52  * will produce the following html
>   53  * <p>
>   54  * {@code
>   55  *     Please see <a
> href="https://www.oracle.com/pls/topic/lookup?ctx=javase9&id=Borealis">a
> spectacular</a> sight.
>   56  * }
>   57  * }
>   58  */
>
>
> The indentation in both the comment and the source code is a bit
> inconsistent. Is that an extra } on line 57?
>
> The regex will fail if there are too many spaces between "{@extLink"
> and the name.   [1]
>
> -- Jon
>
>
> [1]:
> https://blog.codinghorror.com/regular-expressions-now-you-have-two-problems/
>
>
> On 04/18/2017 11:26 AM, Kumar Srinivasan wrote:
>>
>> Thanks Erik, yes will wait for Magnus' and Jon's comments.
>>
>> Kumar
>>
>>> The build change looks ok to me, but Magnus should definitely look
>>> at this since he is so heavily involved in the Javadoc build right now.
>>>
>>> /Erik
>>>
>>>
>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>> Hello,
>>>>
>>>> As explained in the JBS issue [1], this new taglet enables API
>>>> documents
>>>> to contain the extLink tag to link external sources.
>>>>
>>>> Please review the webrev [2].
>>>>
>>>> Thanks
>>>> Kumar
>>>>
>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>
>>
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Kumar Srinivasan
In reply to this post by David Holmes

We could potentially make the default URL to be "some" cgi url,
and have the build system specify the  URL all the time, in our
case it would be the Oracle documentation URL.

Would this be an acceptable approach ?

Kumar

> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>> Hello,
>>>
>>> As explained in the JBS issue [1], this new taglet enables API
>>> documents
>>> to contain the extLink tag to link external sources.
>>>
>>> Please review the webrev [2].
>> Changes looks good.
>>
>> Just a reflection: This is heavily biased to Oracle documentation. Even
>> if it's possible to override the URL via a system property, it assumes
>> the Oracle URL format and id name. Just wondering a bit how that fits
>> with the OpenJDK philosophy.
>
> I have to agree, this is not at all general purpose but totally Oracle
> documentation centric.
>
> David
> -----
>
>
>> /Magnus
>>
>>>
>>> Thanks
>>> Kumar
>>>
>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

David Holmes
On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>
> We could potentially make the default URL to be "some" cgi url,
> and have the build system specify the  URL all the time, in our
> case it would be the Oracle documentation URL.
>
> Would this be an acceptable approach ?

I'm not sure what you mean. I have a hard time seeing how a simple
identifier (that will be fixed in the file using the taglet) can be
attached to an arbitrary URL to yield a valid result. As Magnus said,
being able to change the URL is good, but it still requires the same
"kind" of URL where the identifier is used as a key.

Imagine you have all the documentation locally on your machine then try
to figure out how you could link to other local documentation using this
scheme.

David

> Kumar
>
>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>> Hello,
>>>>
>>>> As explained in the JBS issue [1], this new taglet enables API
>>>> documents
>>>> to contain the extLink tag to link external sources.
>>>>
>>>> Please review the webrev [2].
>>> Changes looks good.
>>>
>>> Just a reflection: This is heavily biased to Oracle documentation. Even
>>> if it's possible to override the URL via a system property, it assumes
>>> the Oracle URL format and id name. Just wondering a bit how that fits
>>> with the OpenJDK philosophy.
>>
>> I have to agree, this is not at all general purpose but totally Oracle
>> documentation centric.
>>
>> David
>> -----
>>
>>
>>> /Magnus
>>>
>>>>
>>>> Thanks
>>>> Kumar
>>>>
>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Please review: JDK-8178725: provide way to link to external documentation

Kumar Srinivasan

On 4/19/2017 1:37 PM, David Holmes wrote:

> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>
>> We could potentially make the default URL to be "some" cgi url,
>> and have the build system specify the  URL all the time, in our
>> case it would be the Oracle documentation URL.
>>
>> Would this be an acceptable approach ?
>
> I'm not sure what you mean. I have a hard time seeing how a simple
> identifier (that will be fixed in the file using the taglet) can be
> attached to an arbitrary URL to yield a valid result. As Magnus said,
> being able to change the URL is good, but it still requires the same
> "kind" of URL where the identifier is used as a key.
>
> Imagine you have all the documentation locally on your machine then
> try to figure out how you could link to other local documentation
> using this scheme.


Ok I see, I am going to defer this to Jon Gibbons.

Kumar

>
> David
>
>> Kumar
>>
>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>> Hello,
>>>>>
>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>> documents
>>>>> to contain the extLink tag to link external sources.
>>>>>
>>>>> Please review the webrev [2].
>>>> Changes looks good.
>>>>
>>>> Just a reflection: This is heavily biased to Oracle documentation.
>>>> Even
>>>> if it's possible to override the URL via a system property, it assumes
>>>> the Oracle URL format and id name. Just wondering a bit how that fits
>>>> with the OpenJDK philosophy.
>>>
>>> I have to agree, this is not at all general purpose but totally Oracle
>>> documentation centric.
>>>
>>> David
>>> -----
>>>
>>>
>>>> /Magnus
>>>>
>>>>>
>>>>> Thanks
>>>>> Kumar
>>>>>
>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>
>>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Jonathan Gibbons
In reply to this post by David Holmes
David, Magnus,

Yes, this is somewhat Oracle-specific (more accurately it is
JDK-specific, which is why this is a proposed to be a JDK build-time
taglet, and not a standard tag in the standard doclet), but it is no
worse than the explicit Oracle-specific URLs that have been used up to
now, or the relative links using {@docRoot}/../stuff  which assume that
"stuff " is available nearby somehow.  I would also go further and say
this is better that the existing methodology because it abstracts all
the linking to a single taglet, removing it from inline in the doc
comments.  Yes, the currently proposed taglet may assume the existence
of  single "base URL", but anyone with an alternate implementation of
OpenJDK could change the impl of the taglet to use any other mechanism
to establish the link. Doing a "strings in switch" on the identifier to
select a URL comes to mind, and avoids anyone having to edit the main
source doc comments.

-- Jon



On 04/19/2017 01:37 PM, David Holmes wrote:

> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>
>> We could potentially make the default URL to be "some" cgi url,
>> and have the build system specify the  URL all the time, in our
>> case it would be the Oracle documentation URL.
>>
>> Would this be an acceptable approach ?
>
> I'm not sure what you mean. I have a hard time seeing how a simple
> identifier (that will be fixed in the file using the taglet) can be
> attached to an arbitrary URL to yield a valid result. As Magnus said,
> being able to change the URL is good, but it still requires the same
> "kind" of URL where the identifier is used as a key.
>
> Imagine you have all the documentation locally on your machine then
> try to figure out how you could link to other local documentation
> using this scheme.
>
> David
>
>> Kumar
>>
>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>> Hello,
>>>>>
>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>> documents
>>>>> to contain the extLink tag to link external sources.
>>>>>
>>>>> Please review the webrev [2].
>>>> Changes looks good.
>>>>
>>>> Just a reflection: This is heavily biased to Oracle documentation.
>>>> Even
>>>> if it's possible to override the URL via a system property, it assumes
>>>> the Oracle URL format and id name. Just wondering a bit how that fits
>>>> with the OpenJDK philosophy.
>>>
>>> I have to agree, this is not at all general purpose but totally Oracle
>>> documentation centric.
>>>
>>> David
>>> -----
>>>
>>>
>>>> /Magnus
>>>>
>>>>>
>>>>> Thanks
>>>>> Kumar
>>>>>
>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>
>>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

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

An idea that might make it more flexible would be if the settable
property used as the link used
one of the familiar formatting substitution mechanisms so the id can be
inserted in the link wherever it is needed.   For example, the
PrintStream formatting like %s.
Alternatively, the {0} form of MessageFormat might clash less with the
URL encoding syntax.

$.02, Roger


On 4/19/2017 4:47 PM, Kumar Srinivasan wrote:

>
> On 4/19/2017 1:37 PM, David Holmes wrote:
>> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>>
>>> We could potentially make the default URL to be "some" cgi url,
>>> and have the build system specify the  URL all the time, in our
>>> case it would be the Oracle documentation URL.
>>>
>>> Would this be an acceptable approach ?
>>
>> I'm not sure what you mean. I have a hard time seeing how a simple
>> identifier (that will be fixed in the file using the taglet) can be
>> attached to an arbitrary URL to yield a valid result. As Magnus said,
>> being able to change the URL is good, but it still requires the same
>> "kind" of URL where the identifier is used as a key.
>>
>> Imagine you have all the documentation locally on your machine then
>> try to figure out how you could link to other local documentation
>> using this scheme.
>
>
> Ok I see, I am going to defer this to Jon Gibbons.
>
> Kumar
>
>>
>> David
>>
>>> Kumar
>>>
>>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>>> Hello,
>>>>>>
>>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>>> documents
>>>>>> to contain the extLink tag to link external sources.
>>>>>>
>>>>>> Please review the webrev [2].
>>>>> Changes looks good.
>>>>>
>>>>> Just a reflection: This is heavily biased to Oracle documentation.
>>>>> Even
>>>>> if it's possible to override the URL via a system property, it
>>>>> assumes
>>>>> the Oracle URL format and id name. Just wondering a bit how that fits
>>>>> with the OpenJDK philosophy.
>>>>
>>>> I have to agree, this is not at all general purpose but totally Oracle
>>>> documentation centric.
>>>>
>>>> David
>>>> -----
>>>>
>>>>
>>>>> /Magnus
>>>>>
>>>>>>
>>>>>> Thanks
>>>>>> Kumar
>>>>>>
>>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>>
>>>
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Jonathan Gibbons
In reply to this post by Kumar Srinivasan
OK by me.

-- Jon


On 04/19/2017 10:46 AM, Kumar Srinivasan wrote:

> Have made the following changes:
> * fixed the indentations, basically pointed the IDE and asked it to
>    reformat the whole file
> * fixed regex, to be defensive against leading WS, though the
> DocCommentParser
>    whacks the WS.
>
> Please see updated webrev:
> http://cr.openjdk.java.net/~ksrini/8178725/webrev.01/
>
> Thanks
> Kumar
>
>
> On 4/18/2017 3:27 PM, Jonathan Gibbons wrote:
>> The use of double quotes in the example might lead one to incorrectly
>> believe that they are required.
>>
>> The example should work without the quotes:
>>
>>   43 /**
>>   44  * An inline tag to conveniently insert an external link.
>>   45  * The tag can be used as follows:
>>   46  * {@extLink name description}, for example
>>   47  * <p>
>>   48  * {@code
>>   49  *     Please see {@extLink Borealis a spectacular} sight.
>>   50  * }
>>   51  * <p>
>>   52  * will produce the following html
>>   53  * <p>
>>   54  * {@code
>>   55  *     Please see <a
>> href="https://www.oracle.com/pls/topic/lookup?ctx=javase9&id=Borealis">a
>> spectacular</a> sight.
>>   56  * }
>>   57  * }
>>   58  */
>>
>>
>> The indentation in both the comment and the source code is a bit
>> inconsistent. Is that an extra } on line 57?
>>
>> The regex will fail if there are too many spaces between "{@extLink"
>> and the name.   [1]
>>
>> -- Jon
>>
>>
>> [1]:
>> https://blog.codinghorror.com/regular-expressions-now-you-have-two-problems/
>>
>>
>> On 04/18/2017 11:26 AM, Kumar Srinivasan wrote:
>>>
>>> Thanks Erik, yes will wait for Magnus' and Jon's comments.
>>>
>>> Kumar
>>>
>>>> The build change looks ok to me, but Magnus should definitely look
>>>> at this since he is so heavily involved in the Javadoc build right
>>>> now.
>>>>
>>>> /Erik
>>>>
>>>>
>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>> Hello,
>>>>>
>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>> documents
>>>>> to contain the extLink tag to link external sources.
>>>>>
>>>>> Please review the webrev [2].
>>>>>
>>>>> Thanks
>>>>> Kumar
>>>>>
>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>
>>>
>>
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Magnus Ihse Bursie
In reply to this post by Jonathan Gibbons
On 2017-04-20 20:02, Jonathan Gibbons wrote:

> David, Magnus,
>
> Yes, this is somewhat Oracle-specific (more accurately it is
> JDK-specific, which is why this is a proposed to be a JDK build-time
> taglet, and not a standard tag in the standard doclet), but it is no
> worse than the explicit Oracle-specific URLs that have been used up to
> now, or the relative links using {@docRoot}/../stuff  which assume
> that "stuff " is available nearby somehow.  I would also go further
> and say this is better that the existing methodology because it
> abstracts all the linking to a single taglet, removing it from inline
> in the doc comments.
I agree, it's in no way worse than what already existed. But it shed
light on the somewhat unclear division between online Oracle
documentation and OpenJDK documentation.

Just to be clear: I do not oppose the fix. It looks good to me.

If anything, there was a bit of a clash between on the one hand
providing a means for overriding the URL, but on the other hand not
really making it as general as it could be. Either removing the
possibility to override it (and, as you say, let an alternative
implementation change the code of the taglet itself), or as Roger
suggest, using a more general mechanism like MessageFormat would have
the code make slightly more sense. The simplest way is probably to skip
the property override, which doesn't get used anyhow right now (and
therefore suspect according to "if you don't test it, it is (or will
become) broken").

/Magnus

> Yes, the currently proposed taglet may assume the existence of  single
> "base URL", but anyone with an alternate implementation of OpenJDK
> could change the impl of the taglet to use any other mechanism to
> establish the link. Doing a "strings in switch" on the identifier to
> select a URL comes to mind, and avoids anyone having to edit the main
> source doc comments.
>
> -- Jon
>
>
>
> On 04/19/2017 01:37 PM, David Holmes wrote:
>> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>>
>>> We could potentially make the default URL to be "some" cgi url,
>>> and have the build system specify the  URL all the time, in our
>>> case it would be the Oracle documentation URL.
>>>
>>> Would this be an acceptable approach ?
>>
>> I'm not sure what you mean. I have a hard time seeing how a simple
>> identifier (that will be fixed in the file using the taglet) can be
>> attached to an arbitrary URL to yield a valid result. As Magnus said,
>> being able to change the URL is good, but it still requires the same
>> "kind" of URL where the identifier is used as a key.
>>
>> Imagine you have all the documentation locally on your machine then
>> try to figure out how you could link to other local documentation
>> using this scheme.
>>
>> David
>>
>>> Kumar
>>>
>>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>>> Hello,
>>>>>>
>>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>>> documents
>>>>>> to contain the extLink tag to link external sources.
>>>>>>
>>>>>> Please review the webrev [2].
>>>>> Changes looks good.
>>>>>
>>>>> Just a reflection: This is heavily biased to Oracle documentation.
>>>>> Even
>>>>> if it's possible to override the URL via a system property, it
>>>>> assumes
>>>>> the Oracle URL format and id name. Just wondering a bit how that fits
>>>>> with the OpenJDK philosophy.
>>>>
>>>> I have to agree, this is not at all general purpose but totally Oracle
>>>> documentation centric.
>>>>
>>>> David
>>>> -----
>>>>
>>>>
>>>>> /Magnus
>>>>>
>>>>>>
>>>>>> Thanks
>>>>>> Kumar
>>>>>>
>>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>>
>>>
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Jonathan Gibbons


On 4/20/17 2:53 PM, Magnus Ihse Bursie wrote:

> On 2017-04-20 20:02, Jonathan Gibbons wrote:
>> David, Magnus,
>>
>> Yes, this is somewhat Oracle-specific (more accurately it is
>> JDK-specific, which is why this is a proposed to be a JDK build-time
>> taglet, and not a standard tag in the standard doclet), but it is no
>> worse than the explicit Oracle-specific URLs that have been used up
>> to now, or the relative links using {@docRoot}/../stuff  which assume
>> that "stuff " is available nearby somehow.  I would also go further
>> and say this is better that the existing methodology because it
>> abstracts all the linking to a single taglet, removing it from inline
>> in the doc comments.
> I agree, it's in no way worse than what already existed. But it shed
> light on the somewhat unclear division between online Oracle
> documentation and OpenJDK documentation.
>
> Just to be clear: I do not oppose the fix. It looks good to me.
>
> If anything, there was a bit of a clash between on the one hand
> providing a means for overriding the URL, but on the other hand not
> really making it as general as it could be. Either removing the
> possibility to override it (and, as you say, let an alternative
> implementation change the code of the taglet itself), or as Roger
> suggest, using a more general mechanism like MessageFormat would have
> the code make slightly more sense. The simplest way is probably to
> skip the property override, which doesn't get used anyhow right now
> (and therefore suspect according to "if you don't test it, it is (or
> will become) broken").
>
I'd be OK with removing the ability to override the URL.

-- Jon

> /Magnus
>
>> Yes, the currently proposed taglet may assume the existence of  
>> single "base URL", but anyone with an alternate implementation of
>> OpenJDK could change the impl of the taglet to use any other
>> mechanism to establish the link. Doing a "strings in switch" on the
>> identifier to select a URL comes to mind, and avoids anyone having to
>> edit the main source doc comments.
>>
>> -- Jon
>>
>>
>>
>> On 04/19/2017 01:37 PM, David Holmes wrote:
>>> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>>>
>>>> We could potentially make the default URL to be "some" cgi url,
>>>> and have the build system specify the  URL all the time, in our
>>>> case it would be the Oracle documentation URL.
>>>>
>>>> Would this be an acceptable approach ?
>>>
>>> I'm not sure what you mean. I have a hard time seeing how a simple
>>> identifier (that will be fixed in the file using the taglet) can be
>>> attached to an arbitrary URL to yield a valid result. As Magnus
>>> said, being able to change the URL is good, but it still requires
>>> the same "kind" of URL where the identifier is used as a key.
>>>
>>> Imagine you have all the documentation locally on your machine then
>>> try to figure out how you could link to other local documentation
>>> using this scheme.
>>>
>>> David
>>>
>>>> Kumar
>>>>
>>>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>>>> Hello,
>>>>>>>
>>>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>>>> documents
>>>>>>> to contain the extLink tag to link external sources.
>>>>>>>
>>>>>>> Please review the webrev [2].
>>>>>> Changes looks good.
>>>>>>
>>>>>> Just a reflection: This is heavily biased to Oracle
>>>>>> documentation. Even
>>>>>> if it's possible to override the URL via a system property, it
>>>>>> assumes
>>>>>> the Oracle URL format and id name. Just wondering a bit how that
>>>>>> fits
>>>>>> with the OpenJDK philosophy.
>>>>>
>>>>> I have to agree, this is not at all general purpose but totally
>>>>> Oracle
>>>>> documentation centric.
>>>>>
>>>>> David
>>>>> -----
>>>>>
>>>>>
>>>>>> /Magnus
>>>>>>
>>>>>>>
>>>>>>> Thanks
>>>>>>> Kumar
>>>>>>>
>>>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>>>
>>>>
>>
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Kumar Srinivasan
In reply to this post by Magnus Ihse Bursie
Thanks for all the comments and feed back, I will go with what we have,
for now, likely its not the last time we will be touching this before
jdk9 is done.

Kumar

> On 2017-04-20 20:02, Jonathan Gibbons wrote:
>> David, Magnus,
>>
>> Yes, this is somewhat Oracle-specific (more accurately it is
>> JDK-specific, which is why this is a proposed to be a JDK build-time
>> taglet, and not a standard tag in the standard doclet), but it is no
>> worse than the explicit Oracle-specific URLs that have been used up
>> to now, or the relative links using {@docRoot}/../stuff  which assume
>> that "stuff " is available nearby somehow.  I would also go further
>> and say this is better that the existing methodology because it
>> abstracts all the linking to a single taglet, removing it from inline
>> in the doc comments.
> I agree, it's in no way worse than what already existed. But it shed
> light on the somewhat unclear division between online Oracle
> documentation and OpenJDK documentation.
>
> Just to be clear: I do not oppose the fix. It looks good to me.
>
> If anything, there was a bit of a clash between on the one hand
> providing a means for overriding the URL, but on the other hand not
> really making it as general as it could be. Either removing the
> possibility to override it (and, as you say, let an alternative
> implementation change the code of the taglet itself), or as Roger
> suggest, using a more general mechanism like MessageFormat would have
> the code make slightly more sense. The simplest way is probably to
> skip the property override, which doesn't get used anyhow right now
> (and therefore suspect according to "if you don't test it, it is (or
> will become) broken").
>
> /Magnus
>
>> Yes, the currently proposed taglet may assume the existence of  
>> single "base URL", but anyone with an alternate implementation of
>> OpenJDK could change the impl of the taglet to use any other
>> mechanism to establish the link. Doing a "strings in switch" on the
>> identifier to select a URL comes to mind, and avoids anyone having to
>> edit the main source doc comments.
>>
>> -- Jon
>>
>>
>>
>> On 04/19/2017 01:37 PM, David Holmes wrote:
>>> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>>>
>>>> We could potentially make the default URL to be "some" cgi url,
>>>> and have the build system specify the  URL all the time, in our
>>>> case it would be the Oracle documentation URL.
>>>>
>>>> Would this be an acceptable approach ?
>>>
>>> I'm not sure what you mean. I have a hard time seeing how a simple
>>> identifier (that will be fixed in the file using the taglet) can be
>>> attached to an arbitrary URL to yield a valid result. As Magnus
>>> said, being able to change the URL is good, but it still requires
>>> the same "kind" of URL where the identifier is used as a key.
>>>
>>> Imagine you have all the documentation locally on your machine then
>>> try to figure out how you could link to other local documentation
>>> using this scheme.
>>>
>>> David
>>>
>>>> Kumar
>>>>
>>>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>>>> Hello,
>>>>>>>
>>>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>>>> documents
>>>>>>> to contain the extLink tag to link external sources.
>>>>>>>
>>>>>>> Please review the webrev [2].
>>>>>> Changes looks good.
>>>>>>
>>>>>> Just a reflection: This is heavily biased to Oracle
>>>>>> documentation. Even
>>>>>> if it's possible to override the URL via a system property, it
>>>>>> assumes
>>>>>> the Oracle URL format and id name. Just wondering a bit how that
>>>>>> fits
>>>>>> with the OpenJDK philosophy.
>>>>>
>>>>> I have to agree, this is not at all general purpose but totally
>>>>> Oracle
>>>>> documentation centric.
>>>>>
>>>>> David
>>>>> -----
>>>>>
>>>>>
>>>>>> /Magnus
>>>>>>
>>>>>>>
>>>>>>> Thanks
>>>>>>> Kumar
>>>>>>>
>>>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>>>
>>>>
>>
>

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

Re: Please review: JDK-8178725: provide way to link to external documentation

Kumar Srinivasan
In reply to this post by Magnus Ihse Bursie

Ok updated http://cr.openjdk.java.net/~ksrini/8178725/webrev.02/

In this changeset removed the override as Magnus suggested.

Thanks
Kumar

> On 2017-04-20 20:02, Jonathan Gibbons wrote:
>> David, Magnus,
>>
>> Yes, this is somewhat Oracle-specific (more accurately it is
>> JDK-specific, which is why this is a proposed to be a JDK build-time
>> taglet, and not a standard tag in the standard doclet), but it is no
>> worse than the explicit Oracle-specific URLs that have been used up
>> to now, or the relative links using {@docRoot}/../stuff  which assume
>> that "stuff " is available nearby somehow.  I would also go further
>> and say this is better that the existing methodology because it
>> abstracts all the linking to a single taglet, removing it from inline
>> in the doc comments.
> I agree, it's in no way worse than what already existed. But it shed
> light on the somewhat unclear division between online Oracle
> documentation and OpenJDK documentation.
>
> Just to be clear: I do not oppose the fix. It looks good to me.
>
> If anything, there was a bit of a clash between on the one hand
> providing a means for overriding the URL, but on the other hand not
> really making it as general as it could be. Either removing the
> possibility to override it (and, as you say, let an alternative
> implementation change the code of the taglet itself), or as Roger
> suggest, using a more general mechanism like MessageFormat would have
> the code make slightly more sense. The simplest way is probably to
> skip the property override, which doesn't get used anyhow right now
> (and therefore suspect according to "if you don't test it, it is (or
> will become) broken").
>
> /Magnus
>
>> Yes, the currently proposed taglet may assume the existence of  
>> single "base URL", but anyone with an alternate implementation of
>> OpenJDK could change the impl of the taglet to use any other
>> mechanism to establish the link. Doing a "strings in switch" on the
>> identifier to select a URL comes to mind, and avoids anyone having to
>> edit the main source doc comments.
>>
>> -- Jon
>>
>>
>>
>> On 04/19/2017 01:37 PM, David Holmes wrote:
>>> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>>>
>>>> We could potentially make the default URL to be "some" cgi url,
>>>> and have the build system specify the  URL all the time, in our
>>>> case it would be the Oracle documentation URL.
>>>>
>>>> Would this be an acceptable approach ?
>>>
>>> I'm not sure what you mean. I have a hard time seeing how a simple
>>> identifier (that will be fixed in the file using the taglet) can be
>>> attached to an arbitrary URL to yield a valid result. As Magnus
>>> said, being able to change the URL is good, but it still requires
>>> the same "kind" of URL where the identifier is used as a key.
>>>
>>> Imagine you have all the documentation locally on your machine then
>>> try to figure out how you could link to other local documentation
>>> using this scheme.
>>>
>>> David
>>>
>>>> Kumar
>>>>
>>>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>>>> Hello,
>>>>>>>
>>>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>>>> documents
>>>>>>> to contain the extLink tag to link external sources.
>>>>>>>
>>>>>>> Please review the webrev [2].
>>>>>> Changes looks good.
>>>>>>
>>>>>> Just a reflection: This is heavily biased to Oracle
>>>>>> documentation. Even
>>>>>> if it's possible to override the URL via a system property, it
>>>>>> assumes
>>>>>> the Oracle URL format and id name. Just wondering a bit how that
>>>>>> fits
>>>>>> with the OpenJDK philosophy.
>>>>>
>>>>> I have to agree, this is not at all general purpose but totally
>>>>> Oracle
>>>>> documentation centric.
>>>>>
>>>>> David
>>>>> -----
>>>>>
>>>>>
>>>>>> /Magnus
>>>>>>
>>>>>>>
>>>>>>> Thanks
>>>>>>> Kumar
>>>>>>>
>>>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>>>
>>>>
>>
>

Loading...