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/
