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