Please review: JDK-8178725: provide way to link to external documentation
Kumar Srinivasan
kumar.x.srinivasan at oracle.com
Mon Apr 24 14:19:53 UTC 2017
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/
>>>>>>
>>>>
>>
>
More information about the build-dev
mailing list