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

Jonathan Gibbons jonathan.gibbons at oracle.com
Thu Apr 20 18:02:05 UTC 2017


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/
>>>>
>>




More information about the build-dev mailing list