From jonathan.gibbons at oracle.com Thu Jan 3 23:19:54 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 3 Jan 2019 15:19:54 -0800 Subject: Unclear docs regarding escaping of Windows paths. In-Reply-To: <967711604.20181228134815@am-soft.de> References: <967711604.20181228134815@am-soft.de> Message-ID: Thorsten, I am sorry for the confusion regarding the documentation for argument files in the javadoc tool. From an implementation point of view, javadoc and javac behave the same with regard to argument files. There was no change in behavior between JDK 7 and JDK 8. In JDK 9, support for argument files was added to the Java launcher [1], and the support for argument files in javadoc and javac was upgraded to match that as closely as possible, while retaining as much compatibility as possible with any existing argument files. This was documented in the JDK 9 Release Notes [2], albeit under a javac heading instead of a javadoc heading. The change that you noted in the URIs is just a side-effect of internal changes in the way that the documentation was generated. We removed the documentation for the old implementation from 9, and it is a bug that we did not get to update it with a reference to the new syntax, as described for the Java launcher in [1]. Please also note that the handling of command-line arguments is different from the handling of the contents of argument files. In general, command-line-arguments are managed by the shell being used to issue the command, whether that is bash, ksh, CMD.exe, or a program like Ant or Maven, whereas argument-files are handled by code in the respective tools (java, javac, javadoc, etc) -- Jon [1] https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-4856361B-8BFD-4964-AE84-121F5F6CF111 [2]https://www.oracle.com/technetwork/java/javase/9-notes-3745703.html#JDK-8162810 On 12/28/2018 04:48 AM, Thorsten Sch?ning wrote: > Hi all, > > this question is related to an issue raised for the javadoc plugin of > Maven[1], which doesn't seem to escape paths forwarded to argument > files supported by javadoc on Windows. The problem is that the docs > have changed regarding such details in the last versions of the JDK > and it's unclear currently how to escape paths properly when and what > to not escape etc. > > The following is for Java 7: > >> If a filename contains embedded spaces, put the whole filename in >> double quotes, and double each backslash ("My Files\Stuff.java"). > https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles > > The following from Java 8: > >> If a file name contains embedded spaces, then put the whole file >> name in double quotation marks. > https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html > > In docs of Java 11 that part is completely missing, no mention of > quotes, spaces or backslashes anymore: > > https://docs.oracle.com/en/java/javase/11/javadoc/javadoc-command.html#GUID-EFE927BC-DB00-4876-808C-ED23E1AAEF7D > > If you have a look at the URIs, in former versions of the JDK they > were Windows-specific, while the last one is not. So I guess things > have been refactored and some details of the argument files have been > simply lost by accident. Or it might be by purpose for some reason. > > The interesting thing is that e.g. the following example for parts of > an argument file are still there: > >> -overview \java\jdk9\docs\api\overview-summary.html > But regarding the docs of Java 7 that example is wrong, because it > uses single backslashes only and as MJAVADOC-469 proves, those don't > work properly in paths of argument files. > > So, could someone please have a look at the docs and why such > important details like those for when to escape backslashes have been > removed? And readd some or some more clarification, at least at the > level of JDK 7? > > Even in JDK 7 there's no definitive answer to the question if > backslash is a general escape character, only examples of using them > as such. One is paths under Windows, the other colons in tag names, > which are not mentioned anymore in JDK 11 as well. > > It would be great if this whole thing could be cleared up so that > people generating the argument files know for sure when to escape > backslashes and when not. > > MJAVADOC-469 proposes a regular expression currently which escapes > backslashes if not already escaped or being part of a tag name. That > doesn't handle a mixture of escaped and unescaped backslashes and > applies the replacement to everything in lack of knowing what a path > is currently. But it fixes the one problem with unescaped paths and > shouldn't break too much else in case of wrong escaping. OTOH, it > might be that all backslashes need to be escaped anyway, one simply > doesn't know currently. > >> (?> additionalOption = additionalOption.replaceAll("(? https://issues.apache.org/jira/browse/MJAVADOC-469?focusedCommentId=16729567&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-16729567 > > Before raising this a s bug somewhere, I was trying to get some more > insights here, maybe someone already able and willing to clarify the > docs or able to tell me where to raise a bug etc. I'm feeling a bit > lost currently. > > Thanks! > > [1]: https://issues.apache.org/jira/browse/MJAVADOC-469 > > Mit freundlichen Gr??en, > > Thorsten Sch?ning > From jonathan.gibbons at oracle.com Fri Jan 4 22:46:19 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 4 Jan 2019 14:46:19 -0800 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <98d3a6e1-2c30-cd68-f036-aead52d65811@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> <02869702-93b7-ac9a-8284-47090d825869@oracle.com> <98d3a6e1-2c30-cd68-f036-aead52d65811@oracle.com> Message-ID: DocFilesHandlerImpl.java:198 Why is the `if` statement necessary?? Why would the call on 201 behave differently to the call on 199 when localTagsContent is empty?? As I aid in an earlier review, I think you can replace 198-202 with just 199. HtmlDocletWriter: 431 Use Collections.emptyList instead of null, to simplify 458 HtmlDocletWriter:442 Please don't use the word "header" in this context.? I suggest you follow the convention in Head.java and call the parameter "extraContent". HtmlDocletWriter: 458 Remove null check, and ensure that null is never passed in on 431. Head.java OK, although the old arrangement was deliberate/intentional, looking down the road at better support of stylesheets, I guess the revised version is more logical. -- Jon On 12/25/2018 08:05 PM, Priya Lakshmi Muthuswamy wrote: > > Hi Jon, > > Javadoc styles for header/navbar will appear as it is and will not get > disturbed. > You're assuming that the javadoc styles for the header/navbar will not be affected by the user styles ;-) > I meant for any html content in doc-files, if there is any > user-defined style, then those should override the javadoc styles. > In html head element, default(javadoc) styles will be placed first and > then those defined in doc-file. > > Thanks, > Priya > > On 12/21/2018 9:24 PM, Jonathan Gibbons wrote: > >> I've not yet read the full webrev, but I do have one immediate >> question, given below. >> >> -- Jon >> >> On 12/21/18 2:13 AM, Priya Lakshmi Muthuswamy wrote: >>> >>> Hi Jon, >>> >>> Thanks for the review. >>> >>> I have made the following changes: >>> 1)Added style tag in HtmlTag.java, before we were using style >>> attribute for comparison. >>> 2)utils.getPreamble(element) ignores new lines after html tags, so I >>> can included them while fetching the localHeadTags. >>> 3)In Head.java, used addContent() itself instead of new methods. >>> I had seen the addContent(), but it was adding the content before >>> the scripts/styles tags. >>> The doc-files script/style needed to added at the end of the other >>> styles it that it overrides them. >>> >> This is a red flag.? Why is it important that the user styles >> override the javadoc styles?? Given that we're adding javadoc styles >> for the javadoc header/navbar, isn't it important that those should >> appear as intended? >> >> >>> When I checked the usage of addContent, i see that its been used >>> only by IndexRedirectWriter to include script/noscript tags. >>> I think that can be added at the end of existing tags as well. >>> >>> updated webrev: >>> http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.01/ >>> api: http://cr.openjdk.java.net/~pmuthuswamy/8214738/api/ >>> >>> some of the doc-file with user specific styles. >>> api/jdk.jdi/com/sun/jdi/doc-files/signature.html >>> api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html >>> api/java.desktop/java/awt/doc-files/Modality.html >>> >>> Thanks, >>> Priya >>> >>> On 12/21/2018 3:16 AM, Jonathan Gibbons wrote: >>>> >>>> Priya, >>>> >>>> In DocFilesHandlerImpl, you have a boolean flag titleOrMetaTags. >>>> Since elements never have content, and so never have end >>>> elements, it seems misleading/incorrect to set the flag to true.? >>>> Also, you omit to handle ENTITY in the element, so I added >>>> that in as well.? You could also write this code as a visitor if >>>> you wanted, but the switch form is not too bad. >>>> >>>> I suggest the code should look something like this: >>>> >>>> 205 List<DocTree> localTags = new ArrayList<>(); ?206 boolean >>>> inHead = false; >>>> 207 boolean inTitle = false; loop: 208 for (DocTree dt : dtrees) { >>>> 209 switch (dt.getKind()) { >>>> 210 case START_ELEMENT: >>>> 211 StartElementTree startElem = (StartElementTree) dt; switch >>>> (HtmlTag.get(startElem)) { case HEAD: inHead = true; break;case >>>> META: break; case TITLE: inTitle=true; break; default: if (inHead) >>>> { localTags.add(startElem); } } >>>> 223 break; 224 case END_ELEMENT: ?211 EndElementTree endElem = >>>> (EndElementTree) dt; switch (HtmlTag.get(endElem)) { case HEAD: >>>> break loop; case TITLE: >>>> inTitle = false; >>>> break loop;default: if (inHead) { localTags.add(startElem); } } >>>> 235 break; case ENTITY: 236 case TEXT: >>>> 237 if (inHead && !inTitle) { >>>> 238 localTags.add(dt); >>>> 239 } >>>> 240 break; >>>> 241 } >>>> -- Jon >>>> >>>> On 12/20/2018 11:31 AM, Jonathan Gibbons wrote: >>>>> >>>>> >>>>> >>>>> On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: >>>>>> Hi, >>>>>> >>>>>> Kindly review the fix for >>>>>> https://bugs.openjdk.java.net/browse/JDK-8214738 >>>>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ >>>>>> >>>>>> Thanks, >>>>>> Priya >>>>>> >>>>>> >>>>> >>>>> I don't think you need to add anything (userHeaderTags etc) to Head. >>>>> Head already has the requisite feature, "extraContent" and >>>>> "addContent" >>>>> which can be used to add content into the <head> element. >>>>> >>>>> Re: >>>>> Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) >>>>> Don't use long-winded String comparison when you have type-safe >>>>> comparison. >>>>> In this case, you should be able to do something like >>>>> ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD >>>>> >>>>> getLocalHeaderTags needlessly walks through all the <body> >>>>> element. You can >>>>> break out of the loop once you hit </head>. >>>>> >>>>> DocFilesHandlerImpl:196. >>>>> The "if" statement is a waste of time and effort. The code will >>>>> work perfectly >>>>> well when localTagsContent is an empty list, so you can simplify >>>>> 196-199 to just 197. >>>>> >>>>> TestCopyFiles.java >>>>> (style) re: indenting the continuation of multi-line strings >>>>> The general Java style for breaking long expressions is to break >>>>> before a binary operator, not after. >>>>> The style in other javadoc tests is to not indent the continuation >>>>> expressions, so that it is easier >>>>> to see how the first line and subsequent lines are aligned. >>>>> >>>>> -- Jon >>>> -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190104/ff7d7aaa/attachment.html> From priya.lakshmi.muthuswamy at oracle.com Mon Jan 7 09:20:32 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 7 Jan 2019 14:50:32 +0530 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <d9e466a2-fb3c-9772-ddac-e0e9a3f9b9ab@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> <d4401085-51cb-1c43-8f5d-43e3ca7ce5bf@oracle.com> <b487b1ee-1eb5-3d80-ef53-8c516aa6ceb9@oracle.com> <02869702-93b7-ac9a-8284-47090d825869@oracle.com> <98d3a6e1-2c30-cd68-f036-aead52d65811@oracle.com> <d9e466a2-fb3c-9772-ddac-e0e9a3f9b9ab@oracle.com> Message-ID: <2fb51833-8297-ba6a-d974-17c73f97f98e@oracle.com> Hi Jon, Updated webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.02/ Thanks, Priya On 1/5/2019 4:16 AM, Jonathan Gibbons wrote: > > DocFilesHandlerImpl.java:198 > Why is the `if` statement necessary?? Why would the call on 201 behave > differently to the call on 199 when localTagsContent is empty?? As I > aid in an earlier review, I think you can replace 198-202 with just 199. > > HtmlDocletWriter: 431 > Use Collections.emptyList instead of null, to simplify 458 > > HtmlDocletWriter:442 > Please don't use the word "header" in this context.? I suggest you > follow the convention in Head.java and call the parameter "extraContent". > > HtmlDocletWriter: 458 > Remove null check, and ensure that null is never passed in on 431. > > Head.java > OK, although the old arrangement was deliberate/intentional, looking > down the road at better support of stylesheets, I guess the revised > version is more logical. > > -- Jon > > > On 12/25/2018 08:05 PM, Priya Lakshmi Muthuswamy wrote: >> >> Hi Jon, >> >> Javadoc styles for header/navbar will appear as it is and will not >> get disturbed. >> > > You're assuming that the javadoc styles for the header/navbar will not > be affected by the user styles ;-) > >> I meant for any html content in doc-files, if there is any >> user-defined style, then those should override the javadoc styles. >> In html head element, default(javadoc) styles will be placed first >> and then those defined in doc-file. >> >> Thanks, >> Priya >> >> On 12/21/2018 9:24 PM, Jonathan Gibbons wrote: >> >>> I've not yet read the full webrev, but I do have one immediate >>> question, given below. >>> >>> -- Jon >>> >>> On 12/21/18 2:13 AM, Priya Lakshmi Muthuswamy wrote: >>>> >>>> Hi Jon, >>>> >>>> Thanks for the review. >>>> >>>> I have made the following changes: >>>> 1)Added style tag in HtmlTag.java, before we were using style >>>> attribute for comparison. >>>> 2)utils.getPreamble(element) ignores new lines after html tags, so >>>> I can included them while fetching the localHeadTags. >>>> 3)In Head.java, used addContent() itself instead of new methods. >>>> I had seen the addContent(), but it was adding the content before >>>> the scripts/styles tags. >>>> The doc-files script/style needed to added at the end of the other >>>> styles it that it overrides them. >>>> >>> This is a red flag.? Why is it important that the user styles >>> override the javadoc styles?? Given that we're adding javadoc styles >>> for the javadoc header/navbar, isn't it important that those should >>> appear as intended? >>> >>> >>>> When I checked the usage of addContent, i see that its been used >>>> only by IndexRedirectWriter to include script/noscript tags. >>>> I think that can be added at the end of existing tags as well. >>>> >>>> updated webrev: >>>> http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.01/ >>>> api: http://cr.openjdk.java.net/~pmuthuswamy/8214738/api/ >>>> >>>> some of the doc-file with user specific styles. >>>> api/jdk.jdi/com/sun/jdi/doc-files/signature.html >>>> api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html >>>> api/java.desktop/java/awt/doc-files/Modality.html >>>> >>>> Thanks, >>>> Priya >>>> >>>> On 12/21/2018 3:16 AM, Jonathan Gibbons wrote: >>>>> >>>>> Priya, >>>>> >>>>> In DocFilesHandlerImpl, you have a boolean flag titleOrMetaTags. >>>>> Since <meta> elements never have content, and so never have end >>>>> elements, it seems misleading/incorrect to set the flag to true.? >>>>> Also, you omit to handle ENTITY in the <title> element, so I added >>>>> that in as well.? You could also write this code as a visitor if >>>>> you wanted, but the switch form is not too bad. >>>>> >>>>> I suggest the code should look something like this: >>>>> >>>>> 205 List<DocTree> localTags = new ArrayList<>(); ?206 boolean >>>>> inHead = false; >>>>> 207 boolean inTitle = false; loop: 208 for (DocTree dt : dtrees) { >>>>> 209 switch (dt.getKind()) { >>>>> 210 case START_ELEMENT: >>>>> 211 StartElementTree startElem = (StartElementTree) dt; switch >>>>> (HtmlTag.get(startElem)) { case HEAD: inHead = true; break;case >>>>> META: break; case TITLE: inTitle=true; break; default: if (inHead) >>>>> { localTags.add(startElem); } } >>>>> 223 break; 224 case END_ELEMENT: ?211 EndElementTree endElem = >>>>> (EndElementTree) dt; switch (HtmlTag.get(endElem)) { case HEAD: >>>>> break loop; case TITLE: >>>>> inTitle = false; >>>>> break loop;default: if (inHead) { localTags.add(startElem); } } >>>>> 235 break; case ENTITY: 236 case TEXT: >>>>> 237 if (inHead && !inTitle) { >>>>> 238 localTags.add(dt); >>>>> 239 } >>>>> 240 break; >>>>> 241 } >>>>> -- Jon >>>>> >>>>> On 12/20/2018 11:31 AM, Jonathan Gibbons wrote: >>>>>> >>>>>> >>>>>> >>>>>> On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: >>>>>>> Hi, >>>>>>> >>>>>>> Kindly review the fix for >>>>>>> https://bugs.openjdk.java.net/browse/JDK-8214738 >>>>>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ >>>>>>> >>>>>>> Thanks, >>>>>>> Priya >>>>>>> >>>>>>> >>>>>> >>>>>> I don't think you need to add anything (userHeaderTags etc) to Head. >>>>>> Head already has the requisite feature, "extraContent" and >>>>>> "addContent" >>>>>> which can be used to add content into the <head> element. >>>>>> >>>>>> Re: >>>>>> Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) >>>>>> Don't use long-winded String comparison when you have type-safe >>>>>> comparison. >>>>>> In this case, you should be able to do something like >>>>>> ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD >>>>>> >>>>>> getLocalHeaderTags needlessly walks through all the <body> >>>>>> element. You can >>>>>> break out of the loop once you hit </head>. >>>>>> >>>>>> DocFilesHandlerImpl:196. >>>>>> The "if" statement is a waste of time and effort. The code will >>>>>> work perfectly >>>>>> well when localTagsContent is an empty list, so you can simplify >>>>>> 196-199 to just 197. >>>>>> >>>>>> TestCopyFiles.java >>>>>> (style) re: indenting the continuation of multi-line strings >>>>>> The general Java style for breaking long expressions is to break >>>>>> before a binary operator, not after. >>>>>> The style in other javadoc tests is to not indent the >>>>>> continuation expressions, so that it is easier >>>>>> to see how the first line and subsequent lines are aligned. >>>>>> >>>>>> -- Jon >>>>> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190107/2f317571/attachment.html> From jonathan.gibbons at oracle.com Mon Jan 7 23:09:42 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 7 Jan 2019 15:09:42 -0800 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <2fb51833-8297-ba6a-d974-17c73f97f98e@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> <d4401085-51cb-1c43-8f5d-43e3ca7ce5bf@oracle.com> <b487b1ee-1eb5-3d80-ef53-8c516aa6ceb9@oracle.com> <02869702-93b7-ac9a-8284-47090d825869@oracle.com> <98d3a6e1-2c30-cd68-f036-aead52d65811@oracle.com> <d9e466a2-fb3c-9772-ddac-e0e9a3f9b9ab@oracle.com> <2fb51833-8297-ba6a-d974-17c73f97f98e@oracle.com> Message-ID: <43d2a7d8-01d7-9987-31d7-b8f5f01d7444@oracle.com> OK. In Head.java. consider simplifying 266-268 to ??? extraContent.forEach(tree::addContent); No need for another review. -- Jon On 01/07/2019 01:20 AM, Priya Lakshmi Muthuswamy wrote: > > Hi Jon, > > Updated webrev : > http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.02/ > > Thanks, > Priya > > On 1/5/2019 4:16 AM, Jonathan Gibbons wrote: >> >> DocFilesHandlerImpl.java:198 >> Why is the `if` statement necessary?? Why would the call on 201 >> behave differently to the call on 199 when localTagsContent is >> empty?? As I aid in an earlier review, I think you can replace >> 198-202 with just 199. >> >> HtmlDocletWriter: 431 >> Use Collections.emptyList instead of null, to simplify 458 >> >> HtmlDocletWriter:442 >> Please don't use the word "header" in this context.? I suggest you >> follow the convention in Head.java and call the parameter "extraContent". >> >> HtmlDocletWriter: 458 >> Remove null check, and ensure that null is never passed in on 431. >> >> Head.java >> OK, although the old arrangement was deliberate/intentional, looking >> down the road at better support of stylesheets, I guess the revised >> version is more logical. >> >> -- Jon >> >> >> On 12/25/2018 08:05 PM, Priya Lakshmi Muthuswamy wrote: >>> >>> Hi Jon, >>> >>> Javadoc styles for header/navbar will appear as it is and will not >>> get disturbed. >>> >> >> You're assuming that the javadoc styles for the header/navbar will >> not be affected by the user styles ;-) >> >>> I meant for any html content in doc-files, if there is any >>> user-defined style, then those should override the javadoc styles. >>> In html head element, default(javadoc) styles will be placed first >>> and then those defined in doc-file. >>> >>> Thanks, >>> Priya >>> >>> On 12/21/2018 9:24 PM, Jonathan Gibbons wrote: >>> >>>> I've not yet read the full webrev, but I do have one immediate >>>> question, given below. >>>> >>>> -- Jon >>>> >>>> On 12/21/18 2:13 AM, Priya Lakshmi Muthuswamy wrote: >>>>> >>>>> Hi Jon, >>>>> >>>>> Thanks for the review. >>>>> >>>>> I have made the following changes: >>>>> 1)Added style tag in HtmlTag.java, before we were using style >>>>> attribute for comparison. >>>>> 2)utils.getPreamble(element) ignores new lines after html tags, so >>>>> I can included them while fetching the localHeadTags. >>>>> 3)In Head.java, used addContent() itself instead of new methods. >>>>> I had seen the addContent(), but it was adding the content before >>>>> the scripts/styles tags. >>>>> The doc-files script/style needed to added at the end of the other >>>>> styles it that it overrides them. >>>>> >>>> This is a red flag.? Why is it important that the user styles >>>> override the javadoc styles?? Given that we're adding javadoc >>>> styles for the javadoc header/navbar, isn't it important that those >>>> should appear as intended? >>>> >>>> >>>>> When I checked the usage of addContent, i see that its been used >>>>> only by IndexRedirectWriter to include script/noscript tags. >>>>> I think that can be added at the end of existing tags as well. >>>>> >>>>> updated webrev: >>>>> http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.01/ >>>>> api: http://cr.openjdk.java.net/~pmuthuswamy/8214738/api/ >>>>> >>>>> some of the doc-file with user specific styles. >>>>> api/jdk.jdi/com/sun/jdi/doc-files/signature.html >>>>> api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html >>>>> api/java.desktop/java/awt/doc-files/Modality.html >>>>> >>>>> Thanks, >>>>> Priya >>>>> >>>>> On 12/21/2018 3:16 AM, Jonathan Gibbons wrote: >>>>>> >>>>>> Priya, >>>>>> >>>>>> In DocFilesHandlerImpl, you have a boolean flag titleOrMetaTags. >>>>>> Since <meta> elements never have content, and so never have end >>>>>> elements, it seems misleading/incorrect to set the flag to true.? >>>>>> Also, you omit to handle ENTITY in the <title> element, so I >>>>>> added that in as well.? You could also write this code as a >>>>>> visitor if you wanted, but the switch form is not too bad. >>>>>> >>>>>> I suggest the code should look something like this: >>>>>> >>>>>> 205 List<DocTree> localTags = new ArrayList<>(); ?206 boolean >>>>>> inHead = false; >>>>>> 207 boolean inTitle = false; loop: 208 for (DocTree dt : dtrees) { >>>>>> 209 switch (dt.getKind()) { >>>>>> 210 case START_ELEMENT: >>>>>> 211 StartElementTree startElem = (StartElementTree) dt; switch >>>>>> (HtmlTag.get(startElem)) { case HEAD: inHead = true; break;case >>>>>> META: break; case TITLE: inTitle=true; break; default: if >>>>>> (inHead) { localTags.add(startElem); } } >>>>>> 223 break; 224 case END_ELEMENT: ?211 EndElementTree endElem = >>>>>> (EndElementTree) dt; switch (HtmlTag.get(endElem)) { case HEAD: >>>>>> break loop; case TITLE: >>>>>> inTitle = false; >>>>>> break loop;default: if (inHead) { localTags.add(startElem); } } >>>>>> 235 break; case ENTITY: 236 case TEXT: >>>>>> 237 if (inHead && !inTitle) { >>>>>> 238 localTags.add(dt); >>>>>> 239 } >>>>>> 240 break; >>>>>> 241 } >>>>>> -- Jon >>>>>> >>>>>> On 12/20/2018 11:31 AM, Jonathan Gibbons wrote: >>>>>>> >>>>>>> >>>>>>> >>>>>>> On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: >>>>>>>> Hi, >>>>>>>> >>>>>>>> Kindly review the fix for >>>>>>>> https://bugs.openjdk.java.net/browse/JDK-8214738 >>>>>>>> webrev : >>>>>>>> http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ >>>>>>>> >>>>>>>> Thanks, >>>>>>>> Priya >>>>>>>> >>>>>>>> >>>>>>> >>>>>>> I don't think you need to add anything (userHeaderTags etc) to Head. >>>>>>> Head already has the requisite feature, "extraContent" and >>>>>>> "addContent" >>>>>>> which can be used to add content into the <head> element. >>>>>>> >>>>>>> Re: >>>>>>> Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) >>>>>>> Don't use long-winded String comparison when you have type-safe >>>>>>> comparison. >>>>>>> In this case, you should be able to do something like >>>>>>> ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD >>>>>>> >>>>>>> getLocalHeaderTags needlessly walks through all the <body> >>>>>>> element. You can >>>>>>> break out of the loop once you hit </head>. >>>>>>> >>>>>>> DocFilesHandlerImpl:196. >>>>>>> The "if" statement is a waste of time and effort. The code will >>>>>>> work perfectly >>>>>>> well when localTagsContent is an empty list, so you can simplify >>>>>>> 196-199 to just 197. >>>>>>> >>>>>>> TestCopyFiles.java >>>>>>> (style) re: indenting the continuation of multi-line strings >>>>>>> The general Java style for breaking long expressions is to break >>>>>>> before a binary operator, not after. >>>>>>> The style in other javadoc tests is to not indent the >>>>>>> continuation expressions, so that it is easier >>>>>>> to see how the first line and subsequent lines are aligned. >>>>>>> >>>>>>> -- Jon >>>>>> >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190107/22ac1b2a/attachment.html> From jonathan.gibbons at oracle.com Tue Jan 8 01:06:32 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 7 Jan 2019 17:06:32 -0800 Subject: RFR: JDK-8216319: Refactor JavadocTester to allow more on-by-default checkers; add A11YChecker Message-ID: <3cc17ed9-2fa9-d01f-8407-fa2c3f5cc72c@oracle.com> Please review a medium-simple change to refactor JavadocTester to allow more on-by-default checkers, and to introduce a new checker The nested classes for HtmlParser and LinkChecker are moved out of JavadocTester to become top-level classes; a new interface HtmlChecker is introduced between HtmlParser and LinkChecker, and a new subtype of that interface is added. The A11YChecker is currently simple ... when enabled, it checks for content outside of a region in HTML 5 files, and it checks for out-of-order headings. We may want to add additional checks in future. Architectural limitations in JavadocTester mean it is simpler/easier to read each file for each checker, meaning that if both checkers are enabled, the files will be read/parsed twice. This is in contrast to DocCheck where each file is read once and the checkers are run in parallel. However, relatively speaking the number and size of the files is small (compared to, say, the JDK API docs), and the overhead is not noticeable, and preferable to any more substantial refactoring of JavadocTester at this time. A11yChecker is not enabled by default at this time: it finds lots of errors related to out-of-order headings; however, it is expected that when we fix that issue, A11yChecker will then be enabled by default. -- Jon JBS: https://bugs.openjdk.java.net/browse/JDK-8216319 Webrev: http://cr.openjdk.java.net/~jjg/8216319/webrev.00/ From hannes.wallnoefer at oracle.com Tue Jan 8 10:33:30 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Tue, 8 Jan 2019 11:33:30 +0100 Subject: RFR: JDK-8216319: Refactor JavadocTester to allow more on-by-default checkers; add A11YChecker In-Reply-To: <3cc17ed9-2fa9-d01f-8407-fa2c3f5cc72c@oracle.com> References: <3cc17ed9-2fa9-d01f-8407-fa2c3f5cc72c@oracle.com> Message-ID: <84292741-F431-4082-89EB-24E8A00A6F5F@oracle.com> In A11yChecker#checkHeading(String) I think the currLevel = level assignment should always be executed. Currently it is only executed if there?s an error, that doesn?t look right. In LinkChecker there are unused private fields: xml, errors; badSchemes is assigned but never read. Other than that everything looks good to me. Hannes > Am 08.01.2019 um 02:06 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>: > > Please review a medium-simple change to refactor JavadocTester to allow more on-by-default checkers, and to introduce a new checker > > The nested classes for HtmlParser and LinkChecker are moved out of JavadocTester to become top-level classes; a new interface HtmlChecker is introduced between HtmlParser and LinkChecker, and a new subtype of that interface is added. > > The A11YChecker is currently simple ... when enabled, it checks for content outside of a region in HTML 5 files, and it checks for out-of-order headings. We may want to add additional checks in future. > > Architectural limitations in JavadocTester mean it is simpler/easier to read each file for each checker, meaning that if both checkers are enabled, the files will be read/parsed twice. This is in contrast to DocCheck where each file is read once and the checkers are run in parallel. However, relatively speaking the number and size of the files is small (compared to, say, the JDK API docs), and the overhead is not noticeable, and preferable to any more substantial refactoring of JavadocTester at this time. > > A11yChecker is not enabled by default at this time: it finds lots of errors related to out-of-order headings; however, it is expected that when we fix that issue, A11yChecker will then be enabled by default. > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8216319 > Webrev: http://cr.openjdk.java.net/~jjg/8216319/webrev.00/ > > From priya.lakshmi.muthuswamy at oracle.com Tue Jan 8 12:11:06 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Tue, 8 Jan 2019 17:41:06 +0530 Subject: RFR : 8199892 : Missing landmarks when generating docs using html sources Message-ID: <85461cfa-2c62-be6c-492f-7c367fbad6a5@oracle.com> Hi, Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8199892 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8199892/webrev.00/ Thanks, Priya From tschoening at am-soft.de Mon Jan 7 11:46:33 2019 From: tschoening at am-soft.de (=?utf-8?Q?Thorsten_Sch=C3=B6ning?=) Date: Mon, 7 Jan 2019 12:46:33 +0100 Subject: Unclear docs regarding escaping of Windows paths. In-Reply-To: <da26f55c-b110-50e9-e18c-5720d2934d3f@oracle.com> References: <967711604.20181228134815@am-soft.de> <da26f55c-b110-50e9-e18c-5720d2934d3f@oracle.com> Message-ID: <159872871.20190107124633@am-soft.de> Guten Tag Jonathan Gibbons, am Freitag, 4. Januar 2019 um 00:19 schrieben Sie: > The change that you noted in the URIs is just a side-effect of internal > changes in the way that the documentation was generated. We removed the > documentation for the old implementation from 9, and it is a bug that we > did not get to update it with a reference to the new syntax, as > described for the Java launcher in [1]. Do you take care of creating a bug adding such a reference? [1] make some points a lot more clear and is actually what I hoped to find. So thanks for that. > Please also note that the handling of command-line arguments is > different from the handling of the contents of argument files.[...] My link is explicitly mentioning argument files: > Examples > Single Argument File[...] > Two Argument Files https://docs.oracle.com/en/java/javase/11/javadoc/javadoc-command.html#GUID-EFE927BC-DB00-4876-808C-ED23E1AAEF7D And the example for Windows contains the following: > -overview \java\jdk9\docs\api\overview-summary.html > -sourcepath \java\ Which uses unescaped backslashs and should be a bug as per your linked [1]. Am I wrong or do you take care of that as well or should I add some bug somewhere or ...? Mit freundlichen Gr??en, Thorsten Sch?ning -- Thorsten Sch?ning E-Mail: Thorsten.Schoening at AM-SoFT.de AM-SoFT IT-Systeme http://www.AM-SoFT.de/ Telefon...........05151- 9468- 55 Fax...............05151- 9468- 88 Mobil..............0178-8 9468- 04 AM-SoFT GmbH IT-Systeme, Brandenburger Str. 7c, 31789 Hameln AG Hannover HRB 207 694 - Gesch?ftsf?hrer: Andreas Muchow From jonathan.gibbons at oracle.com Thu Jan 10 21:44:50 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 10 Jan 2019 13:44:50 -0800 Subject: Unclear docs regarding escaping of Windows paths. In-Reply-To: <159872871.20190107124633@am-soft.de> References: <967711604.20181228134815@am-soft.de> <da26f55c-b110-50e9-e18c-5720d2934d3f@oracle.com> <159872871.20190107124633@am-soft.de> Message-ID: <fe46b985-92bb-04eb-f2f0-b263f55eff91@oracle.com> I've filed JDK-8216522 [1] to track this general issue. For JDK 9 onward, the syntax rules in this area come down to: * outside of quotes, the backslash character has no special meaning and is treated literally * inside quotes, the backslash character is an escape character, and must be doubled to pass through a backslash character. As an example, the following are equivalent C:\Users\me\myfile.java "C:\\Users\\me\\myfile.java" Likewise the following are equivalent C:\Program" "Files\myfile.java "C:\\Program Files\\myfile.java" So, in terms of specifying paths, you only need to be careful if tyhe path contains whitespace characters. -- Jon [1]: https://bugs.openjdk.java.net/browse/JDK-8216522 On 01/07/2019 03:46 AM, Thorsten Sch?ning wrote: > Guten Tag Jonathan Gibbons, > am Freitag, 4. Januar 2019 um 00:19 schrieben Sie: > >> The change that you noted in the URIs is just a side-effect of internal >> changes in the way that the documentation was generated. We removed the >> documentation for the old implementation from 9, and it is a bug that we >> did not get to update it with a reference to the new syntax, as >> described for the Java launcher in [1]. > Do you take care of creating a bug adding such a reference? [1] make > some points a lot more clear and is actually what I hoped to find. So > thanks for that. > >> Please also note that the handling of command-line arguments is >> different from the handling of the contents of argument files.[...] > My link is explicitly mentioning argument files: > >> Examples >> Single Argument File[...] >> Two Argument Files > https://docs.oracle.com/en/java/javase/11/javadoc/javadoc-command.html#GUID-EFE927BC-DB00-4876-808C-ED23E1AAEF7D > > And the example for Windows contains the following: > >> -overview \java\jdk9\docs\api\overview-summary.html >> -sourcepath \java\ > Which uses unescaped backslashs and should be a bug as per your linked > [1]. Am I wrong or do you take care of that as well or should I add > some bug somewhere or ...? > > Mit freundlichen Gr??en, > > Thorsten Sch?ning > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190110/cd1bb541/attachment.html> From jonathan.gibbons at oracle.com Thu Jan 10 22:06:51 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 10 Jan 2019 14:06:51 -0800 Subject: Unclear docs regarding escaping of Windows paths. In-Reply-To: <fe46b985-92bb-04eb-f2f0-b263f55eff91@oracle.com> References: <967711604.20181228134815@am-soft.de> <da26f55c-b110-50e9-e18c-5720d2934d3f@oracle.com> <159872871.20190107124633@am-soft.de> <fe46b985-92bb-04eb-f2f0-b263f55eff91@oracle.com> Message-ID: <2ff2169c-0cb5-baa5-30c6-0f73fc995de1@oracle.com> Thorsten, FWIW, the primary change in the new implementation of arg files that appeared in JDK 9 is that embedded quotes are supported. Previously, if characters within a string needed to be escaped, the entire string had to be escaped. Now, you can escape just part of a string.? In general, all "old-style" files should be accepted as before, but now you have more flexibility over how you quote a string to escape parts of it. -- Jon On 01/10/2019 01:44 PM, Jonathan Gibbons wrote: > > I've filed JDK-8216522 [1] to track this general issue. > > For JDK 9 onward, the syntax rules in this area come down to: > > * outside of quotes, the backslash character has no special meaning > and is treated literally > > * inside quotes, the backslash character is an escape character, and > must be doubled to pass through a backslash character. > > As an example, the following are equivalent > > C:\Users\me\myfile.java > > "C:\\Users\\me\\myfile.java" > > > Likewise the following are equivalent > > C:\Program" "Files\myfile.java > > "C:\\Program Files\\myfile.java" > > So, in terms of specifying paths, you only need to be careful if tyhe > path contains whitespace characters. > > > -- Jon > > > [1]: https://bugs.openjdk.java.net/browse/JDK-8216522 > > > > On 01/07/2019 03:46 AM, Thorsten Sch?ning wrote: >> Guten Tag Jonathan Gibbons, >> am Freitag, 4. Januar 2019 um 00:19 schrieben Sie: >> >>> The change that you noted in the URIs is just a side-effect of internal >>> changes in the way that the documentation was generated. We removed the >>> documentation for the old implementation from 9, and it is a bug that we >>> did not get to update it with a reference to the new syntax, as >>> described for the Java launcher in [1]. >> Do you take care of creating a bug adding such a reference? [1] make >> some points a lot more clear and is actually what I hoped to find. So >> thanks for that. >> >>> Please also note that the handling of command-line arguments is >>> different from the handling of the contents of argument files.[...] >> My link is explicitly mentioning argument files: >> >>> Examples >>> Single Argument File[...] >>> Two Argument Files >> https://docs.oracle.com/en/java/javase/11/javadoc/javadoc-command.html#GUID-EFE927BC-DB00-4876-808C-ED23E1AAEF7D >> >> And the example for Windows contains the following: >> >>> -overview \java\jdk9\docs\api\overview-summary.html >>> -sourcepath \java\ >> Which uses unescaped backslashs and should be a bug as per your linked >> [1]. Am I wrong or do you take care of that as well or should I add >> some bug somewhere or ...? >> >> Mit freundlichen Gr??en, >> >> Thorsten Sch?ning >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190110/653c4ff0/attachment.html> From jonathan.gibbons at oracle.com Fri Jan 11 00:44:11 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 10 Jan 2019 16:44:11 -0800 Subject: RFR JDK12: 8212233: javadoc fails on jdk12 with "The code being documented uses modules but the packages defined in $URL are in the unnamed module." Message-ID: <07a95d39-9f17-3a8b-da58-5ea66c04d764@oracle.com> Please review a small but important fix for javadoc in JDK 12 to have it better support linking to API docs generated from automatic modules and to fix "false-positive" error messages. An automatic module is a jar file without module-info.class, and for which the module name is inferred from the name of the jar file or from an entry in the JAR manifest.? The API docs for such a jar will typically not be structured with a file-name component named for the module. In other words, the API docs are organized as though it's an unnamed module. The fix is to disable the module/package compatibility check for an automatic module, and to roll over to checking the extern link data for the unnamed module if no item is found for it as a named module.? While the logic of the fix is reasonable, it requires backdoor access to some currently-internal info to determine if a module is an automatic module. This functionality should be made available in public API in the next release, and the fix changed to use that new API. There is a new test, which constructs a library JAR file and corresponding API docs. It then creates additional API to reference that library API, testing access to the library as an automatic module from a named and unnamed module, and testing access from a named module to the library API when it is placed in the unnamed module on the classpath. The fourth case of testing links from code in the unnamed module to additional code in the unnamed module is covered by existing tests. In all cases, the test verifies explicitly that the correct link is generated, and the standard built-in link checker verifies that no other links are broken. -- Jon JBS: https://bugs.openjdk.java.net/browse/JDK-8212233 Webrev: http://cr.openjdk.java.net/~jjg/8212233/webrev.00/ From priya.lakshmi.muthuswamy at oracle.com Fri Jan 11 06:23:02 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Fri, 11 Jan 2019 11:53:02 +0530 Subject: RFR : 8199892 : Missing landmarks when generating docs using html sources In-Reply-To: <85461cfa-2c62-be6c-492f-7c367fbad6a5@oracle.com> References: <85461cfa-2c62-be6c-492f-7c367fbad6a5@oracle.com> Message-ID: <c4e6b5a7-5ab4-1171-9ab9-7551602f86e0@oracle.com> Correctly the typo in the test file name. webrev: http://cr.openjdk.java.net/~pmuthuswamy/8199892/webrev.01/ Thanks, Priya On 1/8/2019 5:41 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8199892 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8199892/webrev.00/ > > Thanks, > Priya > > From jonathan.gibbons at oracle.com Fri Jan 11 21:13:15 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 11 Jan 2019 13:13:15 -0800 Subject: RFR : 8199892 : Missing landmarks when generating docs using html sources In-Reply-To: <c4e6b5a7-5ab4-1171-9ab9-7551602f86e0@oracle.com> References: <85461cfa-2c62-be6c-492f-7c367fbad6a5@oracle.com> <c4e6b5a7-5ab4-1171-9ab9-7551602f86e0@oracle.com> Message-ID: <8d50d0dd-7de6-0221-c5ec-a56e7fee1e4b@oracle.com> OK, The long fully-qualified references to the internal HtmlTag are unfortunate. We might want to work on being able to fix that, but that can be done later. In the meantime, you might want to split the long lines. (No re-review necessary) -- Jon On 01/10/2019 10:23 PM, Priya Lakshmi Muthuswamy wrote: > Correctly the typo in the test file name. > webrev: http://cr.openjdk.java.net/~pmuthuswamy/8199892/webrev.01/ > > Thanks, > Priya > > On 1/8/2019 5:41 PM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review the fix for >> https://bugs.openjdk.java.net/browse/JDK-8199892 >> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8199892/webrev.00/ >> >> Thanks, >> Priya >> >> From rick.hillegas at gmail.com Sat Jan 12 17:23:34 2019 From: rick.hillegas at gmail.com (Rick Hillegas) Date: Sat, 12 Jan 2019 09:23:34 -0800 Subject: best practice for including images in the javadoc headers of module descriptors Message-ID: <79f760e9-24c9-2949-8c32-24206362c2b6@gmail.com> I would appreciate your advice about the best practice for handling the following problem. The structure of the generated javadoc tree appears to have changed substantially between Java 9 and Java 11. I noticed this because my module descriptors include <img> tags, which pull corresponding module diagrams into the module overview pages generated by javadoc. The <img> tags have src attributes with relative file references. Here, for instance, is the <img> tag from the javadoc header in the Derby engine's module descriptor: ?* <div style="text-align:center;"> ?*?? <img ?*???? src="resources/engine.svg" ?*???? alt="module diagram for org.apache.derby.engine" ?*???? border="2" ?*?? /> ?* </div> When I build the javadoc using Java 9, browsers correctly display the module diagrams because the module overview pages are in the same directory as the top-level index.html. However, when I build the javadoc using Java 11, the module overview pages live in subdirectories of that top-level root--in this case, in the org.apache.derby.engine subdirectory. What is the best practice for including images in module descriptor headers so that the resulting javadoc displays correctly regardless of whether one builds it using JDK 9 or JDK 11? Thanks, -Rick -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190112/70978baa/attachment.html> From priya.lakshmi.muthuswamy at oracle.com Mon Jan 14 08:55:58 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 14 Jan 2019 14:25:58 +0530 Subject: RFR JDK12: 8212233: javadoc fails on jdk12 with "The code being documented uses modules but the packages defined in $URL are in the unnamed module." In-Reply-To: <07a95d39-9f17-3a8b-da58-5ea66c04d764@oracle.com> References: <07a95d39-9f17-3a8b-da58-5ea66c04d764@oracle.com> Message-ID: <c543fc65-85ad-f57e-ab54-cff46d1ae1e9@oracle.com> +1 -Priya (Not a "R"eviewer) On 1/11/2019 6:14 AM, Jonathan Gibbons wrote: > Please review a small but important fix for javadoc in JDK 12 to have > it better support linking to API docs generated from automatic modules > and to fix "false-positive" error messages. > > An automatic module is a jar file without module-info.class, and for > which the module name is inferred from the name of the jar file or > from an entry in the JAR manifest.? The API docs for such a jar will > typically not be structured with a file-name component named for the > module. In other words, the API docs are organized as though it's an > unnamed module. > > The fix is to disable the module/package compatibility check for an > automatic module, and to roll over to checking the extern link data > for the unnamed module if no item is found for it as a named module.? > While the logic of the fix is reasonable, it requires backdoor access > to some currently-internal info to determine if a module is an > automatic module. This functionality should be made available in > public API in the next release, and the fix changed to use that new API. > > There is a new test, which constructs a library JAR file and > corresponding API docs. It then creates additional API to reference > that library API, testing access to the library as an automatic module > from a named and unnamed module, and testing access from a named > module to the library API when it is placed in the unnamed module on > the classpath. The fourth case of testing links from code in the > unnamed module to additional code in the unnamed module is covered by > existing tests. In all cases, the test verifies explicitly that the > correct link is generated, and the standard built-in link checker > verifies that no other links are broken. > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8212233 > Webrev: http://cr.openjdk.java.net/~jjg/8212233/webrev.00/ > > > From priya.lakshmi.muthuswamy at oracle.com Mon Jan 14 12:04:13 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 14 Jan 2019 17:34:13 +0530 Subject: RFR: 8202626 : javadoc generates broken links to <Unnamed> Message-ID: <81dd9937-adc9-60f1-c1b6-582ac2305115@oracle.com> Hi, Kindly review the changes for https://bugs.openjdk.java.net/browse/JDK-8202626 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202626/webrev.00/ Thanks, Priya From jonathan.gibbons at oracle.com Tue Jan 15 00:46:49 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 14 Jan 2019 16:46:49 -0800 Subject: RFR: 8217034, , JavadocTester should check for missing files by default Message-ID: <f84683d4-0e7c-e820-6c78-43505b820e0e@oracle.com> Please review a mostly "test only" fix to have JavadocTester treat links to missing files in the generated output as an error. Currently, it detects and reports such files, but they are not treated as serious enough to cause the test to fail. The primary fix to JavadocTester is a trivial one-liner, to bump the error count when missing files are found. The catch is that doing so causes a number of tests to fail, which need to be fixed up. Most of these are "benign" failures, caused by issues in the way that the test was written, without expecting that links would ever be validated. In one case, the problem is in the javadoc tool itself, in which the "wrong" stylesheet is written into a redirect fiile. The fault there is mostly benign as well, since no stylesheet is actually required, but it is enough to cause a link checker to notice. Here is an explanation of the edits: test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java ??? The one-line change to treat links to missing files as a serious error src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java ??? Use the correct stylesheet in the redirect file. The difference is when a non-default stylesheet is given on the command line. This is at best a workaround solution. Arguably a better solution is to make it so that if no stylesheet(s) are given to Head.java, then no links to stylesheets are generated, but that is a more pervasive change that is out of scope for this mostly test-only fix. test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java test/langtools/jdk/javadoc/doclet/testBreakIterator/pkg/BreakIteratorTest.java ??? The test generates a reference to a file that is not generated. The code is modified to reference a similar file that is generated. test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootInlineTag.java test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootTag.java ??? Same as previous. The test generates a reference to a file that is not generated. The code is modified to reference a similar file that is generated. test/langtools/jdk/javadoc/doclet/testDocRootLink/TestDocRootLink.java ??? For this one, the automatic link check is disabled. There are details given in the test itself. Because of the pattern of the bad links, it does not seem appropriate to synthesize targets for the links, as is done in other cases. test/langtools/jdk/javadoc/doclet/testHtmlLandmarkRegions/TestHtmlLandmarkRegions.java test/langtools/jdk/javadoc/doclet/testIndexWithModules/TestIndexWithModules.java ??? There's something going on here that seems to be a different problem. Filed JDK-8217013. The link checker is disabled in this test until 8217013 is fixed. test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java ??? The example code has toy/bad links. The automatic link checker is disabled for those instances where the toy links cause the test to fail. test/langtools/jdk/javadoc/doclet/testOptions/TestOptions.java ??? This is the test that fails if the src/.../IndexRedirectWriter is not updated. It tests the stylesheet options that cause the "wrong" stylesheet to be generated in the index. It seems appropriate to tag this bug (and just this bug) as the test for the change to the src file. test/langtools/jdk/javadoc/doclet/testRelativeLinks/TestRelativeLinks.java ??? This test has a bunch of toy links that don't exist, and which cannot easily be generated by javadoc tool. Since the test is specifically about testing the handling of different sorts of links, it seems better to synthesize the missing/expected files rather than disable the link checker for this test. test/langtools/jdk/javadoc/doclet/testCopyFiles/packages/p2/doc-files/theme.css ??? For this test, we just create/use a dummy empty file in the repo that is enough to keep the link checker happy. ----- -- Jon JBS: https://bugs.openjdk.java.net/browse/JDK-8217034 Webrev: http://cr.openjdk.java.net/~jjg/8217034/webrev.00 -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190114/2a459b37/attachment.html> From hannes.wallnoefer at oracle.com Tue Jan 15 16:57:27 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Tue, 15 Jan 2019 17:57:27 +0100 Subject: RFR JDK12: 8212233: javadoc fails on jdk12 with "The code being documented uses modules but the packages defined in $URL are in the unnamed module." In-Reply-To: <07a95d39-9f17-3a8b-da58-5ea66c04d764@oracle.com> References: <07a95d39-9f17-3a8b-da58-5ea66c04d764@oracle.com> Message-ID: <871105E3-CFE1-47B4-8AAF-9909913DA676@oracle.com> The test file contains mixed space/tabs indentation. Otherwise looks good. Hannes > Am 11.01.2019 um 01:44 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>: > > Please review a small but important fix for javadoc in JDK 12 to have it better support linking to API docs generated from automatic modules and to fix "false-positive" error messages. > > An automatic module is a jar file without module-info.class, and for which the module name is inferred from the name of the jar file or from an entry in the JAR manifest. The API docs for such a jar will typically not be structured with a file-name component named for the module. In other words, the API docs are organized as though it's an unnamed module. > > The fix is to disable the module/package compatibility check for an automatic module, and to roll over to checking the extern link data for the unnamed module if no item is found for it as a named module. While the logic of the fix is reasonable, it requires backdoor access to some currently-internal info to determine if a module is an automatic module. This functionality should be made available in public API in the next release, and the fix changed to use that new API. > > There is a new test, which constructs a library JAR file and corresponding API docs. It then creates additional API to reference that library API, testing access to the library as an automatic module from a named and unnamed module, and testing access from a named module to the library API when it is placed in the unnamed module on the classpath. The fourth case of testing links from code in the unnamed module to additional code in the unnamed module is covered by existing tests. In all cases, the test verifies explicitly that the correct link is generated, and the standard built-in link checker verifies that no other links are broken. > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8212233 > Webrev: http://cr.openjdk.java.net/~jjg/8212233/webrev.00/ > > > From jonathan.gibbons at oracle.com Tue Jan 15 21:58:38 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 15 Jan 2019 13:58:38 -0800 Subject: RFR: JDK-8216319: Refactor JavadocTester to allow more on-by-default checkers; add A11YChecker In-Reply-To: <84292741-F431-4082-89EB-24E8A00A6F5F@oracle.com> References: <3cc17ed9-2fa9-d01f-8407-fa2c3f5cc72c@oracle.com> <84292741-F431-4082-89EB-24E8A00A6F5F@oracle.com> Message-ID: <09d1d58e-4f1d-5833-6096-31d45299bd95@oracle.com> Thanks.? I've addressed those issues. I'll wait a bit to push this work to avoid merge conflicts with stuff coming in from 12. -- Jon On 01/08/2019 02:33 AM, Hannes Walln?fer wrote: > In A11yChecker#checkHeading(String) I think the currLevel = level assignment should always be executed. Currently it is only executed if there?s an error, that doesn?t look right. > > In LinkChecker there are unused private fields: xml, errors; badSchemes is assigned but never read. > > Other than that everything looks good to me. > > Hannes > >> Am 08.01.2019 um 02:06 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>: >> >> Please review a medium-simple change to refactor JavadocTester to allow more on-by-default checkers, and to introduce a new checker >> >> The nested classes for HtmlParser and LinkChecker are moved out of JavadocTester to become top-level classes; a new interface HtmlChecker is introduced between HtmlParser and LinkChecker, and a new subtype of that interface is added. >> >> The A11YChecker is currently simple ... when enabled, it checks for content outside of a region in HTML 5 files, and it checks for out-of-order headings. We may want to add additional checks in future. >> >> Architectural limitations in JavadocTester mean it is simpler/easier to read each file for each checker, meaning that if both checkers are enabled, the files will be read/parsed twice. This is in contrast to DocCheck where each file is read once and the checkers are run in parallel. However, relatively speaking the number and size of the files is small (compared to, say, the JDK API docs), and the overhead is not noticeable, and preferable to any more substantial refactoring of JavadocTester at this time. >> >> A11yChecker is not enabled by default at this time: it finds lots of errors related to out-of-order headings; however, it is expected that when we fix that issue, A11yChecker will then be enabled by default. >> >> -- Jon >> >> JBS: https://bugs.openjdk.java.net/browse/JDK-8216319 >> Webrev: http://cr.openjdk.java.net/~jjg/8216319/webrev.00/ >> >> From jonathan.gibbons at oracle.com Tue Jan 15 23:02:17 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 15 Jan 2019 15:02:17 -0800 Subject: RFR: JDK-8217214: Recent new javadoc test needs to be updated Message-ID: <e60116ff-c029-b3df-3de0-f01fc4ea2a80@oracle.com> Please review this trivial change to reconcile a bad merge. One changeset added a new test which depends on the JavadocTester library; a different changeset moved the library.? The test needs to be updated for the new location of the library in its new package. There is no other change in functionality. Change is inline, below. JBS: https://bugs.openjdk.java.net/browse/JDK-8217214 -- Jon $ hg diff diff -r 142b179dd60e test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOptionWithAutomaticModule.java --- a/test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOptionWithAutomaticModule.java Tue Jan 15 19:24:07 2019 -0300 +++ b/test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOptionWithAutomaticModule.java Tue Jan 15 14:56:25 2019 -0800 @@ -25,12 +25,12 @@ ? * @test ? * @bug 8212233 ? * @summary The code being documented uses modules but the packages defined in $URL are in the unnamed module. - * @library /tools/lib ../lib + * @library /tools/lib ../../lib ? * @modules ? *????? jdk.javadoc/jdk.javadoc.internal.tool ? *????? jdk.compiler/com.sun.tools.javac.api ? *????? jdk.compiler/com.sun.tools.javac.main - * @build JavadocTester toolbox.JarTask toolbox.JavacTask toolbox.ModuleBuilder toolbox.ToolBox + * @build javadoc.tester.* toolbox.JarTask toolbox.JavacTask toolbox.ModuleBuilder toolbox.ToolBox ? * @run main TestLinkOptionWithAutomaticModule ? */ @@ -43,6 +43,8 @@ ?import toolbox.ModuleBuilder; ?import toolbox.ToolBox; +import javadoc.tester.JavadocTester; + ?public class TestLinkOptionWithAutomaticModule extends JavadocTester { ???? public static void main(String... args) throws Exception { From joe.darcy at oracle.com Wed Jan 16 00:06:28 2019 From: joe.darcy at oracle.com (Joe Darcy) Date: Tue, 15 Jan 2019 16:06:28 -0800 Subject: RFR: JDK-8217214: Recent new javadoc test needs to be updated In-Reply-To: <e60116ff-c029-b3df-3de0-f01fc4ea2a80@oracle.com> References: <e60116ff-c029-b3df-3de0-f01fc4ea2a80@oracle.com> Message-ID: <c5b1fd50-0fba-330a-4247-af3bd1a2176c@oracle.com> +1 -Joe On 1/15/2019 3:02 PM, Jonathan Gibbons wrote: > Please review this trivial change to reconcile a bad merge. > > One changeset added a new test which depends on the JavadocTester > library; a different changeset moved the library.? The test needs to > be updated for the new location of the library in its new package. > There is no other change in functionality. > > Change is inline, below. > JBS: https://bugs.openjdk.java.net/browse/JDK-8217214 > > -- Jon > > > $ hg diff > diff -r 142b179dd60e > test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOptionWithAutomaticModule.java > --- > a/test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOptionWithAutomaticModule.java > Tue Jan 15 19:24:07 2019 -0300 > +++ > b/test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOptionWithAutomaticModule.java > Tue Jan 15 14:56:25 2019 -0800 > @@ -25,12 +25,12 @@ > ? * @test > ? * @bug 8212233 > ? * @summary The code being documented uses modules but the packages > defined in $URL are in the unnamed module. > - * @library /tools/lib ../lib > + * @library /tools/lib ../../lib > ? * @modules > ? *????? jdk.javadoc/jdk.javadoc.internal.tool > ? *????? jdk.compiler/com.sun.tools.javac.api > ? *????? jdk.compiler/com.sun.tools.javac.main > - * @build JavadocTester toolbox.JarTask toolbox.JavacTask > toolbox.ModuleBuilder toolbox.ToolBox > + * @build javadoc.tester.* toolbox.JarTask toolbox.JavacTask > toolbox.ModuleBuilder toolbox.ToolBox > ? * @run main TestLinkOptionWithAutomaticModule > ? */ > > @@ -43,6 +43,8 @@ > ?import toolbox.ModuleBuilder; > ?import toolbox.ToolBox; > > +import javadoc.tester.JavadocTester; > + > ?public class TestLinkOptionWithAutomaticModule extends JavadocTester { > > ???? public static void main(String... args) throws Exception { > From jonathan.gibbons at oracle.com Wed Jan 16 00:10:38 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 15 Jan 2019 16:10:38 -0800 Subject: best practice for including images in the javadoc headers of module descriptors In-Reply-To: <79f760e9-24c9-2949-8c32-24206362c2b6@gmail.com> References: <79f760e9-24c9-2949-8c32-24206362c2b6@gmail.com> Message-ID: <245b36b1-ea10-53f6-3ab0-c2f4e2f967e8@oracle.com> Rick, There is, temporarily, an option to javadoc called --no-module-directories, which in JDK 11 will give you the same directory layout as in JDK 9. However, the layout in JDK 9 is bad insofar as like-named packages in different modules will overwrite each other, and so, in time, the layout in JDK 11, with an extra level of directory for the module name, will be the only supported layout. So, to answer your question ... ... short term answer, use --no-module-directories ... long term answer, put content for a module in the module-specific directory ... or at least, create references appropriate to that layout Separately, FYI. I notice you are using the "border" attribute in your <img> tag, which probably implies you are using HTML 4.? If you are using the -html4 option, you should be getting a warning that support for HTML4 will be going away at some point. If you are not using the -html4 option, and are using the default (-html5), then you're probably generating bad HTML which may not pass a conformance checker and/or may not display correctly in all browsers. -- Jon On 01/12/2019 09:23 AM, Rick Hillegas wrote: > > I would appreciate your advice about the best practice for handling > the following problem. > > The structure of the generated javadoc tree appears to have changed > substantially between Java 9 and Java 11. I noticed this because my > module descriptors include <img> tags, which pull corresponding module > diagrams into the module overview pages generated by javadoc. The > <img> tags have src attributes with relative file references. Here, > for instance, is the <img> tag from the javadoc header in the Derby > engine's module descriptor: > > ?* <div style="text-align:center;"> > ?*?? <img > ?*???? src="resources/engine.svg" > ?*???? alt="module diagram for org.apache.derby.engine" > ?*???? border="2" > ?*?? /> > ?* </div> > > > When I build the javadoc using Java 9, browsers correctly display the > module diagrams because the module overview pages are in the same > directory as the top-level index.html. However, when I build the > javadoc using Java 11, the module overview pages live in > subdirectories of that top-level root--in this case, in the > org.apache.derby.engine subdirectory. > > What is the best practice for including images in module descriptor > headers so that the resulting javadoc displays correctly regardless of > whether one builds it using JDK 9 or JDK 11? > > Thanks, > -Rick > From jonathan.gibbons at oracle.com Wed Jan 16 00:22:22 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 15 Jan 2019 16:22:22 -0800 Subject: best practice for including images in the javadoc headers of module descriptors In-Reply-To: <245b36b1-ea10-53f6-3ab0-c2f4e2f967e8@oracle.com> References: <79f760e9-24c9-2949-8c32-24206362c2b6@gmail.com> <245b36b1-ea10-53f6-3ab0-c2f4e2f967e8@oracle.com> Message-ID: <64b2d7fe-5dc2-de7a-ccb1-0d22cb300f73@oracle.com> Rick, I found your Derby documentation online with the module diagrams. Very nice! I don't know how much you have looked at how we insert the module diagrams into the JDK API documentation, but we do it with a custom taglet, which gives us the flexibility to vary the output. For example, if the images are not available, we don't generate references to them. Using that sort of technique would be another way to address your original question. -- Jon On 01/15/2019 04:10 PM, Jonathan Gibbons wrote: > Rick, > > There is, temporarily, an option to javadoc called > --no-module-directories, which in JDK 11 will give you the same > directory layout as in JDK 9. > > However, the layout in JDK 9 is bad insofar as like-named packages in > different modules will overwrite each other, and so, in time, the > layout in JDK 11, with an extra level of directory for the module > name, will be the only supported layout. > > So, to answer your question ... > > ... short term answer, use --no-module-directories > > ... long term answer, put content for a module in the module-specific > directory ... or at least, create references appropriate to that layout > > > Separately, FYI. I notice you are using the "border" attribute in your > <img> tag, which probably implies you are using HTML 4.? If you are > using the -html4 option, you should be getting a warning that support > for HTML4 will be going away at some point. If you are not using the > -html4 option, and are using the default (-html5), then you're > probably generating bad HTML which may not pass a conformance checker > and/or may not display correctly in all browsers. > > -- Jon > > > On 01/12/2019 09:23 AM, Rick Hillegas wrote: >> >> I would appreciate your advice about the best practice for handling >> the following problem. >> >> The structure of the generated javadoc tree appears to have changed >> substantially between Java 9 and Java 11. I noticed this because my >> module descriptors include <img> tags, which pull corresponding >> module diagrams into the module overview pages generated by javadoc. >> The <img> tags have src attributes with relative file references. >> Here, for instance, is the <img> tag from the javadoc header in the >> Derby engine's module descriptor: >> >> ??* <div style="text-align:center;"> >> ??*?? <img >> ??*???? src="resources/engine.svg" >> ??*???? alt="module diagram for org.apache.derby.engine" >> ??*???? border="2" >> ??*?? /> >> ??* </div> >> >> >> When I build the javadoc using Java 9, browsers correctly display the >> module diagrams because the module overview pages are in the same >> directory as the top-level index.html. However, when I build the >> javadoc using Java 11, the module overview pages live in >> subdirectories of that top-level root--in this case, in the >> org.apache.derby.engine subdirectory. >> >> What is the best practice for including images in module descriptor >> headers so that the resulting javadoc displays correctly regardless >> of whether one builds it using JDK 9 or JDK 11? >> >> Thanks, >> -Rick >> > From jonathan.gibbons at oracle.com Wed Jan 16 00:25:47 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 15 Jan 2019 16:25:47 -0800 Subject: RFR: 8217034, , JavadocTester should check for missing files by default In-Reply-To: <f84683d4-0e7c-e820-6c78-43505b820e0e@oracle.com> References: <f84683d4-0e7c-e820-6c78-43505b820e0e@oracle.com> Message-ID: <78cf7044-6583-e888-c9c8-081fc62b10e4@oracle.com> Updated webrev to accommodate the recent refactoring of JavadocTester. The only difference is that one-line change that was previously in JavadocTester is now in LinkChecker. -- Jon JBS: https://bugs.openjdk.java.net/browse/JDK-8217034 Webrev: http://cr.openjdk.java.net/~jjg/8217034/webrev.01 On 01/14/2019 04:46 PM, Jonathan Gibbons wrote: > > Please review a mostly "test only" fix to have JavadocTester treat > links to missing files in the generated output as an error. > > Currently, it detects and reports such files, but they are not treated > as serious enough to cause the test to fail. > > The primary fix to JavadocTester is a trivial one-liner, to bump the > error count when missing files are found. > > The catch is that doing so causes a number of tests to fail, which > need to be fixed up. Most of these are "benign" failures, caused by > issues in the way that the test was written, without expecting that > links would ever be validated. In one case, the problem is in the > javadoc tool itself, in which the "wrong" stylesheet is written into a > redirect fiile. The fault there is mostly benign as well, since no > stylesheet is actually required, but it is enough to cause a link > checker to notice. > > Here is an explanation of the edits: > > > test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java > > ??? The one-line change to treat links to missing files as a serious error > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java > > ??? Use the correct stylesheet in the redirect file. The difference is > when a non-default stylesheet is given on the command line. This is at > best a workaround solution. Arguably a better solution is to make it > so that if no stylesheet(s) are given to Head.java, then no links to > stylesheets are generated, but that is a more pervasive change that is > out of scope for this mostly test-only fix. > > test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java > test/langtools/jdk/javadoc/doclet/testBreakIterator/pkg/BreakIteratorTest.java > > ??? The test generates a reference to a file that is not generated. > The code is modified to reference a similar file that is generated. > > test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootInlineTag.java > test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootTag.java > > > ??? Same as previous. The test generates a reference to a file that is > not generated. The code is modified to reference a similar file that > is generated. > > test/langtools/jdk/javadoc/doclet/testDocRootLink/TestDocRootLink.java > > ??? For this one, the automatic link check is disabled. There are > details given in the test itself. Because of the pattern of the bad > links, it does not seem appropriate to synthesize targets for the > links, as is done in other cases. > > test/langtools/jdk/javadoc/doclet/testHtmlLandmarkRegions/TestHtmlLandmarkRegions.java > test/langtools/jdk/javadoc/doclet/testIndexWithModules/TestIndexWithModules.java > > ??? There's something going on here that seems to be a different > problem. Filed JDK-8217013. The link checker is disabled in this test > until 8217013 is fixed. > > test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java > > ??? The example code has toy/bad links. The automatic link checker is > disabled for those instances where the toy links cause the test to fail. > > test/langtools/jdk/javadoc/doclet/testOptions/TestOptions.java > > ??? This is the test that fails if the src/.../IndexRedirectWriter is > not updated. It tests the stylesheet options that cause the "wrong" > stylesheet to be generated in the index. It seems appropriate to tag > this bug (and just this bug) as the test for the change to the src file. > > test/langtools/jdk/javadoc/doclet/testRelativeLinks/TestRelativeLinks.java > > ??? This test has a bunch of toy links that don't exist, and which > cannot easily be generated by javadoc tool. Since the test is > specifically about testing the handling of different sorts of links, > it seems better to synthesize the missing/expected files rather than > disable the link checker for this test. > > > test/langtools/jdk/javadoc/doclet/testCopyFiles/packages/p2/doc-files/theme.css > > ??? For this test, we just create/use a dummy empty file in the repo > that is enough to keep the link checker happy. > > > ----- > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8217034 > Webrev: http://cr.openjdk.java.net/~jjg/8217034/webrev.00 > > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190115/958d9d4b/attachment.html> From jonathan.gibbons at oracle.com Wed Jan 16 00:39:54 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 15 Jan 2019 16:39:54 -0800 Subject: RFR: 8202626 : javadoc generates broken links to <Unnamed> In-Reply-To: <81dd9937-adc9-60f1-c1b6-582ac2305115@oracle.com> References: <81dd9937-adc9-60f1-c1b6-582ac2305115@oracle.com> Message-ID: <ee1a37ba-e923-7289-9650-4fd2afeee876@oracle.com> Nice. I'm pleased it was a relatively simple fix. Thumbs-up. -- Jon On 01/14/2019 04:04 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the changes for > https://bugs.openjdk.java.net/browse/JDK-8202626 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202626/webrev.00/ > > Thanks, > Priya > From rick.hillegas at gmail.com Wed Jan 16 00:43:11 2019 From: rick.hillegas at gmail.com (Rick Hillegas) Date: Tue, 15 Jan 2019 16:43:11 -0800 Subject: best practice for including images in the javadoc headers of module descriptors In-Reply-To: <64b2d7fe-5dc2-de7a-ccb1-0d22cb300f73@oracle.com> References: <79f760e9-24c9-2949-8c32-24206362c2b6@gmail.com> <245b36b1-ea10-53f6-3ab0-c2f4e2f967e8@oracle.com> <64b2d7fe-5dc2-de7a-ccb1-0d22cb300f73@oracle.com> Message-ID: <be79c8e6-6da4-ba46-8b9e-564628d085fa@gmail.com> Thanks for that advice, Jon. On 1/15/19 4:22 PM, Jonathan Gibbons wrote: > Rick, > > I found your Derby documentation online with the module diagrams. Very > nice! > > I don't know how much you have looked at how we insert the module > diagrams into the JDK API documentation, but we do it with a custom > taglet, which gives us the flexibility to vary the output. For > example, if the images are not available, we don't generate references > to them. Using that sort of technique would be another way to address > your original question. > > -- Jon > > > On 01/15/2019 04:10 PM, Jonathan Gibbons wrote: >> Rick, >> >> There is, temporarily, an option to javadoc called >> --no-module-directories, which in JDK 11 will give you the same >> directory layout as in JDK 9. >> >> However, the layout in JDK 9 is bad insofar as like-named packages in >> different modules will overwrite each other, and so, in time, the >> layout in JDK 11, with an extra level of directory for the module >> name, will be the only supported layout. >> >> So, to answer your question ... >> >> ... short term answer, use --no-module-directories >> >> ... long term answer, put content for a module in the module-specific >> directory ... or at least, create references appropriate to that layout >> >> >> Separately, FYI. I notice you are using the "border" attribute in >> your <img> tag, which probably implies you are using HTML 4.? If you >> are using the -html4 option, you should be getting a warning that >> support for HTML4 will be going away at some point. If you are not >> using the -html4 option, and are using the default (-html5), then >> you're probably generating bad HTML which may not pass a conformance >> checker and/or may not display correctly in all browsers. >> >> -- Jon >> >> >> On 01/12/2019 09:23 AM, Rick Hillegas wrote: >>> >>> I would appreciate your advice about the best practice for handling >>> the following problem. >>> >>> The structure of the generated javadoc tree appears to have changed >>> substantially between Java 9 and Java 11. I noticed this because my >>> module descriptors include <img> tags, which pull corresponding >>> module diagrams into the module overview pages generated by javadoc. >>> The <img> tags have src attributes with relative file references. >>> Here, for instance, is the <img> tag from the javadoc header in the >>> Derby engine's module descriptor: >>> >>> ??* <div style="text-align:center;"> >>> ??*?? <img >>> ??*???? src="resources/engine.svg" >>> ??*???? alt="module diagram for org.apache.derby.engine" >>> ??*???? border="2" >>> ??*?? /> >>> ??* </div> >>> >>> >>> When I build the javadoc using Java 9, browsers correctly display >>> the module diagrams because the module overview pages are in the >>> same directory as the top-level index.html. However, when I build >>> the javadoc using Java 11, the module overview pages live in >>> subdirectories of that top-level root--in this case, in the >>> org.apache.derby.engine subdirectory. >>> >>> What is the best practice for including images in module descriptor >>> headers so that the resulting javadoc displays correctly regardless >>> of whether one builds it using JDK 9 or JDK 11? >>> >>> Thanks, >>> -Rick >>> >> > > From hannes.wallnoefer at oracle.com Fri Jan 18 10:23:43 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Fri, 18 Jan 2019 11:23:43 +0100 Subject: RFR: 8217034, , JavadocTester should check for missing files by default In-Reply-To: <78cf7044-6583-e888-c9c8-081fc62b10e4@oracle.com> References: <f84683d4-0e7c-e820-6c78-43505b820e0e@oracle.com> <78cf7044-6583-e888-c9c8-081fc62b10e4@oracle.com> Message-ID: <FC542741-BE40-4BF2-9BCF-69B677416566@oracle.com> Looks good! Hannes > Am 16.01.2019 um 01:25 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>: > > Updated webrev to accommodate the recent refactoring of JavadocTester. The only difference is that one-line change that was previously in JavadocTester is now in LinkChecker. > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8217034 > Webrev: http://cr.openjdk.java.net/~jjg/8217034/webrev.01 > > > On 01/14/2019 04:46 PM, Jonathan Gibbons wrote: >> Please review a mostly "test only" fix to have JavadocTester treat links to missing files in the generated output as an error. >> Currently, it detects and reports such files, but they are not treated as serious enough to cause the test to fail. >> >> The primary fix to JavadocTester is a trivial one-liner, to bump the error count when missing files are found. >> >> The catch is that doing so causes a number of tests to fail, which need to be fixed up. Most of these are "benign" failures, caused by issues in the way that the test was written, without expecting that links would ever be validated. In one case, the problem is in the javadoc tool itself, in which the "wrong" stylesheet is written into a redirect fiile. The fault there is mostly benign as well, since no stylesheet is actually required, but it is enough to cause a link checker to notice. >> >> Here is an explanation of the edits: >> >> >> test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java >> >> The one-line change to treat links to missing files as a serious error >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java >> >> Use the correct stylesheet in the redirect file. The difference is when a non-default stylesheet is given on the command line. This is at best a workaround solution. Arguably a better solution is to make it so that if no stylesheet(s) are given to Head.java, then no links to stylesheets are generated, but that is a more pervasive change that is out of scope for this mostly test-only fix. >> test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java >> test/langtools/jdk/javadoc/doclet/testBreakIterator/pkg/BreakIteratorTest.java >> >> The test generates a reference to a file that is not generated. The code is modified to reference a similar file that is generated. >> test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootInlineTag.java >> test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootTag.java >> >> Same as previous. The test generates a reference to a file that is not generated. The code is modified to reference a similar file that is generated. >> >> test/langtools/jdk/javadoc/doclet/testDocRootLink/TestDocRootLink.java >> >> For this one, the automatic link check is disabled. There are details given in the test itself. Because of the pattern of the bad links, it does not seem appropriate to synthesize targets for the links, as is done in other cases. >> test/langtools/jdk/javadoc/doclet/testHtmlLandmarkRegions/TestHtmlLandmarkRegions.java >> test/langtools/jdk/javadoc/doclet/testIndexWithModules/TestIndexWithModules.java >> >> There's something going on here that seems to be a different problem. Filed JDK-8217013. The link checker is disabled in this test until 8217013 is fixed. >> >> test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java >> >> The example code has toy/bad links. The automatic link checker is disabled for those instances where the toy links cause the test to fail. >> test/langtools/jdk/javadoc/doclet/testOptions/TestOptions.java >> >> This is the test that fails if the src/.../IndexRedirectWriter is not updated. It tests the stylesheet options that cause the "wrong" stylesheet to be generated in the index. It seems appropriate to tag this bug (and just this bug) as the test for the change to the src file. >> test/langtools/jdk/javadoc/doclet/testRelativeLinks/TestRelativeLinks.java >> >> This test has a bunch of toy links that don't exist, and which cannot easily be generated by javadoc tool. Since the test is specifically about testing the handling of different sorts of links, it seems better to synthesize the missing/expected files rather than disable the link checker for this test. >> >> >> test/langtools/jdk/javadoc/doclet/testCopyFiles/packages/p2/doc-files/theme.css >> For this test, we just create/use a dummy empty file in the repo that is enough to keep the link checker happy. >> >> >> ----- >> >> -- Jon >> >> JBS: https://bugs.openjdk.java.net/browse/JDK-8217034 >> Webrev: http://cr.openjdk.java.net/~jjg/8217034/webrev.00 >> >> >> > From nlisker at gmail.com Fri Jan 18 22:08:22 2019 From: nlisker at gmail.com (Nir Lisker) Date: Sat, 19 Jan 2019 00:08:22 +0200 Subject: Raw String Literals for JavaDoc Message-ID: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> Hi, I sent am email to amber-dev about the possibility of using Raw String Literals in JavaDoc [1]. I was sent here and told there was some discussion in this area. Would what I describe in [1] be possible in some form? Thanks, Nir [1] https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190119/21d54c00/attachment.html> From jonathan.gibbons at oracle.com Fri Jan 18 22:37:09 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 18 Jan 2019 14:37:09 -0800 Subject: Raw String Literals for JavaDoc In-Reply-To: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> References: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> Message-ID: <3c89b370-aaba-38e6-6124-76f3f52fc7f3@oracle.com> Nir, There are some fundamental reasons why it is not possible to all of what you suggest in the way you suggest (i.e. using raw string literals) For the most obvious example, albeit a bit of an obscure case, would be a raw string literal containing a /*...*/ comment. Similar problems apply to the appearance of `@` which already has an existing meaning in documentation comments. That being said, we are already investigating better ways to include code samples and snippets in documentation comments, perhaps by being able to insert code from a "nearby" source file, which would have the advantage that (separately) the source file could itself be compiled to ensure that it is syntactically correct. -- Jon On 01/18/2019 02:08 PM, Nir Lisker wrote: > Hi, > > I sent am email to amber-dev about the possibility of using Raw String > Literals in JavaDoc [1]. I was sent here and told there was some > discussion in this area. Would what I describe in [1] be possible in > some form? > > Thanks, > Nir > > [1] > https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html From nlisker at gmail.com Sun Jan 20 03:38:19 2019 From: nlisker at gmail.com (Nir Lisker) Date: Sun, 20 Jan 2019 05:38:19 +0200 Subject: Raw String Literals for JavaDoc In-Reply-To: <3c89b370-aaba-38e6-6124-76f3f52fc7f3@oracle.com> References: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> <3c89b370-aaba-38e6-6124-76f3f52fc7f3@oracle.com> Message-ID: <CA+0ynh_3xQTFP15Aru5NCDYiVfG++bo1Ff0u+Tfd7YDNZhgstA@mail.gmail.com> Hi Jon, Is any relevant material (discussion/prototype etc.) available to the public or are you not there yet? - Nir On Sat, Jan 19, 2019 at 12:37 AM Jonathan Gibbons < jonathan.gibbons at oracle.com> wrote: > Nir, > > There are some fundamental reasons why it is not possible to all of what > you suggest in the way you suggest (i.e. using raw string literals) For > the most obvious example, albeit a bit of an obscure case, would be a > raw string literal containing a /*...*/ comment. Similar problems apply > to the appearance of `@` which already has an existing meaning in > documentation comments. > > That being said, we are already investigating better ways to include > code samples and snippets in documentation comments, perhaps by being > able to insert code from a "nearby" source file, which would have the > advantage that (separately) the source file could itself be compiled to > ensure that it is syntactically correct. > > -- Jon > > > On 01/18/2019 02:08 PM, Nir Lisker wrote: > > Hi, > > > > I sent am email to amber-dev about the possibility of using Raw String > > Literals in JavaDoc [1]. I was sent here and told there was some > > discussion in this area. Would what I describe in [1] be possible in > > some form? > > > > Thanks, > > Nir > > > > [1] > > > https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190120/975fe692/attachment.html> From jonathan.gibbons at oracle.com Sun Jan 20 17:08:00 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Sun, 20 Jan 2019 09:08:00 -0800 Subject: Raw String Literals for JavaDoc In-Reply-To: <CA+0ynh_3xQTFP15Aru5NCDYiVfG++bo1Ff0u+Tfd7YDNZhgstA@mail.gmail.com> References: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> <3c89b370-aaba-38e6-6124-76f3f52fc7f3@oracle.com> <CA+0ynh_3xQTFP15Aru5NCDYiVfG++bo1Ff0u+Tfd7YDNZhgstA@mail.gmail.com> Message-ID: <f5c995e7-faf9-4f74-c7cd-c86293a9fc18@oracle.com> Nir, We're not there yet; we're just at the brainstorming stage. There is nothing public at this point. Here are some of the high-level points. 1. As far as JLS/javac is concerned, there is nothing special about documentation comments: they are just instances of "/*...*/" comments, which means that we will never be able to support literal unescaped use of "*/" within a comment. 2. For the standard doclet, there is a syntactic assumption about `@` at the beginning of a line, which is used to split the doc comment into an initial run of text, followed by the block tags. This is what causes problems for annotations in code samples. While we could modify that rule, it would mean we would have to do more detailed parsing of every comment, to determine the initial text and block tags. 3. While it is convenient to have "inline snippets" in doc comments, it is worth noting that there have been instances where snippets have been incorrect or invalid. Thus, there is an interest to support out-of-line snippets, taken from external source files, that can separately be compiled and/or tested.? This suggests a tag like `{@example /args/}` or `{@snippet /args/}`. 4. For a tag like `{@snippet /args/}`, the discussion becomes, "what are the args". Two suggestions are: the name of a method whose body to include, or a range of text between markers, given in comments.? Either could work, but then the discussion turns to the use cases. Is this just about snippets to include in the doc comment? Some have suggested that it would be worth being able to link to a copy of the complete source file in the generated documentation, for a big picture example of how to use an API.? If the entire source is to be copied to somewhere in the documentation, then the issue of what delimiters to use for the inline snippet becomes more significant: do you want to see the markers, do you want to have to structure the source to arrange for suitable method boundaries, etc. 5. Some have suggested migrating towards the use of Markdown to replace the use of HTML in doc comments.? While Markdown would give us a new/different way to solve the `<pre>{@code...` problem, it would not solve the issues outlined in any of the preceding discussion. If there is any discussion to be had at this point, I would say it is to understand the use cases. Is this about being able to include multiple small mostly-unrelated snippets of code, such as a few lines of code to give examples of how to use methods in an API, without necessarily being able to also include the entire source file somewhere, or is this about being able to write a high level narrative description, with selected snippets, of a complete working example program? -- Jon On 1/19/19 7:38 PM, Nir Lisker wrote: > Hi Jon, > > Is any relevant material (discussion/prototype etc.) available to the > public or are you not there yet? > > - Nir > > On Sat, Jan 19, 2019 at 12:37 AM Jonathan Gibbons > <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote: > > Nir, > > There are some fundamental reasons why it is not possible to all > of what > you suggest in the way you suggest (i.e. using raw string > literals) For > the most obvious example, albeit a bit of an obscure case, would be a > raw string literal containing a /*...*/ comment. Similar problems > apply > to the appearance of `@` which already has an existing meaning in > documentation comments. > > That being said, we are already investigating better ways to include > code samples and snippets in documentation comments, perhaps by being > able to insert code from a "nearby" source file, which would have the > advantage that (separately) the source file could itself be > compiled to > ensure that it is syntactically correct. > > -- Jon > > > On 01/18/2019 02:08 PM, Nir Lisker wrote: > > Hi, > > > > I sent am email to amber-dev about the possibility of using Raw > String > > Literals in JavaDoc [1]. I was sent here and told there was some > > discussion in this area. Would what I describe in [1] be > possible in > > some form? > > > > Thanks, > > Nir > > > > [1] > > > https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190120/0b990fda/attachment.html> From nlisker at gmail.com Mon Jan 21 01:06:03 2019 From: nlisker at gmail.com (Nir Lisker) Date: Mon, 21 Jan 2019 03:06:03 +0200 Subject: Raw String Literals for JavaDoc In-Reply-To: <f5c995e7-faf9-4f74-c7cd-c86293a9fc18@oracle.com> References: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> <3c89b370-aaba-38e6-6124-76f3f52fc7f3@oracle.com> <CA+0ynh_3xQTFP15Aru5NCDYiVfG++bo1Ff0u+Tfd7YDNZhgstA@mail.gmail.com> <f5c995e7-faf9-4f74-c7cd-c86293a9fc18@oracle.com> Message-ID: <CA+0ynh8bagB9126Q=i1n0nQTXkwWfTUaC44tXz-jcgvrcA-ZpA@mail.gmail.com> The compiled examples idea sounds appealing. Having recently gone over and corrected many snippets for JavaFX controls I can see the usefulness of having them be compile-able. My only worry is that it will require new files just for a few lines of examples each. For example, we have a 'controls' package with classes for Label, Button, TextField etc. We provide an example or two for each control, where would we put these 30 files? How do we not make them load with the classloader, which makes startup time longer? > If there is any discussion to be had at this point, I would say it is to > understand the use cases. > There are 2 use cases that immediately come to mind: 1. A single block as shown in [1]. 2. A broken down block where each segment has a short discussion, as in [2] under Creating a TableView. - Nir [1] https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/Accordion.html [2] https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/TableView.html On Sun, Jan 20, 2019 at 7:08 PM Jonathan Gibbons < jonathan.gibbons at oracle.com> wrote: > Nir, > > We're not there yet; we're just at the brainstorming stage. There is > nothing public at this point. > > Here are some of the high-level points. > > 1. As far as JLS/javac is concerned, there is nothing special about > documentation comments: they are just instances of "/*...*/" comments, > which means that we will never be able to support literal unescaped use of > "*/" within a comment. > > 2. For the standard doclet, there is a syntactic assumption about `@` at > the beginning of a line, which is used to split the doc comment into an > initial run of text, followed by the block tags. This is what causes > problems for annotations in code samples. While we could modify that rule, > it would mean we would have to do more detailed parsing of every comment, > to determine the initial text and block tags. > > 3. While it is convenient to have "inline snippets" in doc comments, it is > worth noting that there have been instances where snippets have been > incorrect or invalid. Thus, there is an interest to support out-of-line > snippets, taken from external source files, that can separately be compiled > and/or tested. This suggests a tag like `{@example *args*}` or `{@snippet > *args*}`. > > 4. For a tag like `{@snippet *args*}`, the discussion becomes, "what are > the args". Two suggestions are: the name of a method whose body to include, > or a range of text between markers, given in comments. Either could work, > but then the discussion turns to the use cases. Is this just about snippets > to include in the doc comment? Some have suggested that it would be worth > being able to link to a copy of the complete source file in the generated > documentation, for a big picture example of how to use an API. If the > entire source is to be copied to somewhere in the documentation, then the > issue of what delimiters to use for the inline snippet becomes more > significant: do you want to see the markers, do you want to have to > structure the source to arrange for suitable method boundaries, etc. > > 5. Some have suggested migrating towards the use of Markdown to replace > the use of HTML in doc comments. While Markdown would give us a > new/different way to solve the `<pre>{@code...` problem, it would not solve > the issues outlined in any of the preceding discussion. > > If there is any discussion to be had at this point, I would say it is to > understand the use cases. Is this about being able to include multiple > small mostly-unrelated snippets of code, such as a few lines of code to > give examples of how to use methods in an API, without necessarily being > able to also include the entire source file somewhere, or is this about > being able to write a high level narrative description, with selected > snippets, of a complete working example program? > > -- Jon > On 1/19/19 7:38 PM, Nir Lisker wrote: > > Hi Jon, > > Is any relevant material (discussion/prototype etc.) available to the > public or are you not there yet? > > - Nir > > On Sat, Jan 19, 2019 at 12:37 AM Jonathan Gibbons < > jonathan.gibbons at oracle.com> wrote: > >> Nir, >> >> There are some fundamental reasons why it is not possible to all of what >> you suggest in the way you suggest (i.e. using raw string literals) For >> the most obvious example, albeit a bit of an obscure case, would be a >> raw string literal containing a /*...*/ comment. Similar problems apply >> to the appearance of `@` which already has an existing meaning in >> documentation comments. >> >> That being said, we are already investigating better ways to include >> code samples and snippets in documentation comments, perhaps by being >> able to insert code from a "nearby" source file, which would have the >> advantage that (separately) the source file could itself be compiled to >> ensure that it is syntactically correct. >> >> -- Jon >> >> >> On 01/18/2019 02:08 PM, Nir Lisker wrote: >> > Hi, >> > >> > I sent am email to amber-dev about the possibility of using Raw String >> > Literals in JavaDoc [1]. I was sent here and told there was some >> > discussion in this area. Would what I describe in [1] be possible in >> > some form? >> > >> > Thanks, >> > Nir >> > >> > [1] >> > >> https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html >> >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190121/681a1aab/attachment-0001.html> From jonathan.gibbons at oracle.com Mon Jan 21 16:07:51 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 21 Jan 2019 08:07:51 -0800 Subject: Raw String Literals for JavaDoc In-Reply-To: <CA+0ynh8bagB9126Q=i1n0nQTXkwWfTUaC44tXz-jcgvrcA-ZpA@mail.gmail.com> References: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> <3c89b370-aaba-38e6-6124-76f3f52fc7f3@oracle.com> <CA+0ynh_3xQTFP15Aru5NCDYiVfG++bo1Ff0u+Tfd7YDNZhgstA@mail.gmail.com> <f5c995e7-faf9-4f74-c7cd-c86293a9fc18@oracle.com> <CA+0ynh8bagB9126Q=i1n0nQTXkwWfTUaC44tXz-jcgvrcA-ZpA@mail.gmail.com> Message-ID: <65e51bd4-750c-a05e-3273-895956ef4b1a@oracle.com> Nir, "where would we put these 30 files?" ... given that one of the goals would be to make it easy to compile the files, the files should probably be in their own source tree, whose root is identified to the standard doclet with a new "path" option, such as `--snippet-path`. Within that source tree, it would be up to the author to organize the files in whatever manner is convenient. You could either have one big source file with lots of snippets within it, or could organize the files in a traditional package hierarchy. I'm not sure I understand the comment about the classloader ... as far as javadoc is concerned, they would just be source files, containing somehow-identifiable snippets; as far as making the files executable, that would be up to the author to make happen as they wish -- issues with startup time would not be relevant to javadoc itself.? Note that by suggesting that the source files should be in their own source tree, it would be up to the author to provide any additional infrastructure to compile/test/run the examples, using the infrastructure of their choice (i.e. Makefile/Ant/Maven/Graal/etc) I agree with your use cases, but the question common to both uses is, would you want to also publish the entire source code for the files containing the snippets ... and would that affect how you would want to identify the snippets within the source files? -- Jon On 1/20/19 5:06 PM, Nir Lisker wrote: > The compiled examples idea sounds appealing. Having recently gone over > and corrected many snippets for JavaFX controls I can see the > usefulness of having them be compile-able. My only worry is that it > will require new files just for a few lines of examples each. For > example, we have a 'controls' package with classes for Label, Button, > TextField etc. We provide an example or two for each control, where > would we put these 30 files? How do we not make them load with the > classloader, which makes startup time longer? > > If there is any discussion to be had at this point, I would say it > is to understand the use cases. > > > ?There are 2 use cases that immediately come to mind: > 1. A single block as shown in [1]. > 2. A broken down block where each segment has a short discussion, as > in [2] under?Creating a TableView. > > - Nir > > [1] > https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/Accordion.html > [2] > https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/TableView.html > > On Sun, Jan 20, 2019 at 7:08 PM Jonathan Gibbons > <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote: > > Nir, > > We're not there yet; we're just at the brainstorming stage. There > is nothing public at this point. > > Here are some of the high-level points. > > 1. As far as JLS/javac is concerned, there is nothing special > about documentation comments: they are just instances of "/*...*/" > comments, which means that we will never be able to support > literal unescaped use of "*/" within a comment. > > 2. For the standard doclet, there is a syntactic assumption about > `@` at the beginning of a line, which is used to split the doc > comment into an initial run of text, followed by the block tags. > This is what causes problems for annotations in code samples. > While we could modify that rule, it would mean we would have to do > more detailed parsing of every comment, to determine the initial > text and block tags. > > 3. While it is convenient to have "inline snippets" in doc > comments, it is worth noting that there have been instances where > snippets have been incorrect or invalid. Thus, there is an > interest to support out-of-line snippets, taken from external > source files, that can separately be compiled and/or tested.? This > suggests a tag like `{@example /args/}` or `{@snippet /args/}`. > > 4. For a tag like `{@snippet /args/}`, the discussion becomes, > "what are the args". Two suggestions are: the name of a method > whose body to include, or a range of text between markers, given > in comments.? Either could work, but then the discussion turns to > the use cases. Is this just about snippets to include in the doc > comment? Some have suggested that it would be worth being able to > link to a copy of the complete source file in the generated > documentation, for a big picture example of how to use an API.? If > the entire source is to be copied to somewhere in the > documentation, then the issue of what delimiters to use for the > inline snippet becomes more significant: do you want to see the > markers, do you want to have to structure the source to arrange > for suitable method boundaries, etc. > > 5. Some have suggested migrating towards the use of Markdown to > replace the use of HTML in doc comments. While Markdown would give > us a new/different way to solve the `<pre>{@code...` problem, it > would not solve the issues outlined in any of the preceding > discussion. > > If there is any discussion to be had at this point, I would say it > is to understand the use cases. Is this about being able to > include multiple small mostly-unrelated snippets of code, such as > a few lines of code to give examples of how to use methods in an > API, without necessarily being able to also include the entire > source file somewhere, or is this about being able to write a high > level narrative description, with selected snippets, of a complete > working example program? > > -- Jon > > On 1/19/19 7:38 PM, Nir Lisker wrote: >> Hi Jon, >> >> Is any relevant material (discussion/prototype etc.) available to >> the public or are you not there yet? >> >> - Nir >> >> On Sat, Jan 19, 2019 at 12:37 AM Jonathan Gibbons >> <jonathan.gibbons at oracle.com >> <mailto:jonathan.gibbons at oracle.com>> wrote: >> >> Nir, >> >> There are some fundamental reasons why it is not possible to >> all of what >> you suggest in the way you suggest (i.e. using raw string >> literals) For >> the most obvious example, albeit a bit of an obscure case, >> would be a >> raw string literal containing a /*...*/ comment. Similar >> problems apply >> to the appearance of `@` which already has an existing >> meaning in >> documentation comments. >> >> That being said, we are already investigating better ways to >> include >> code samples and snippets in documentation comments, perhaps >> by being >> able to insert code from a "nearby" source file, which would >> have the >> advantage that (separately) the source file could itself be >> compiled to >> ensure that it is syntactically correct. >> >> -- Jon >> >> >> On 01/18/2019 02:08 PM, Nir Lisker wrote: >> > Hi, >> > >> > I sent am email to amber-dev about the possibility of using >> Raw String >> > Literals in JavaDoc [1]. I was sent here and told there was >> some >> > discussion in this area. Would what I describe in [1] be >> possible in >> > some form? >> > >> > Thanks, >> > Nir >> > >> > [1] >> > >> https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190121/da3d1f66/attachment.html> From nlisker at gmail.com Thu Jan 24 20:07:55 2019 From: nlisker at gmail.com (Nir Lisker) Date: Thu, 24 Jan 2019 22:07:55 +0200 Subject: Raw String Literals for JavaDoc In-Reply-To: <65e51bd4-750c-a05e-3273-895956ef4b1a@oracle.com> References: <CA+0ynh_5D9FyzWyTSn-2Ryz-jVdwHECJffsb0H82eh2keSWviw@mail.gmail.com> <3c89b370-aaba-38e6-6124-76f3f52fc7f3@oracle.com> <CA+0ynh_3xQTFP15Aru5NCDYiVfG++bo1Ff0u+Tfd7YDNZhgstA@mail.gmail.com> <f5c995e7-faf9-4f74-c7cd-c86293a9fc18@oracle.com> <CA+0ynh8bagB9126Q=i1n0nQTXkwWfTUaC44tXz-jcgvrcA-ZpA@mail.gmail.com> <65e51bd4-750c-a05e-3273-895956ef4b1a@oracle.com> Message-ID: <CA+0ynh_NoJJm2RPXqXy5hO15c7zuLZvMRZ0S4QRUPRoUXB2RCg@mail.gmail.com> The separate source tree does solve my concerns. would you want to also publish the entire source code for the files > containing the snippets > Iv'e given it some thought. I don't think it's necessary to publish the whole source, but it could be useful on occasions. So it comes down to the usual dilemma of effort vs. benefit. For my work on JavaFX, a full source file would include the ceremonies around showing how to use the class (setting up a Stage and a Scene) and the snippet is just the few lines as shown above. On the other hand, JavaFX has tutorials that already have full code examples [1], so I'm doubtful the user would *need* the snippet's source. ... and would that affect how you would want to identify the snippets > within the source files? > I don't think so. If I have a full source and I mark the snippet lines in some way, publishing the full source or not makes no difference, except that maybe the annotation/tag for marking the snippet should not be displayed so that copy-paste is easier. - Nir [1] https://docs.oracle.com/javase/8/javafx/user-interface-tutorial/accordion-titledpane.htm On Mon, Jan 21, 2019 at 6:07 PM Jonathan Gibbons < jonathan.gibbons at oracle.com> wrote: > Nir, > > "where would we put these 30 files?" ... given that one of the goals would > be to make it easy to compile the files, the files should probably be in > their own source tree, whose root is identified to the standard doclet with > a new "path" option, such as `--snippet-path`. Within that source tree, it > would be up to the author to organize the files in whatever manner is > convenient. You could either have one big source file with lots of snippets > within it, or could organize the files in a traditional package hierarchy. > I'm not sure I understand the comment about the classloader ... as far as > javadoc is concerned, they would just be source files, containing > somehow-identifiable snippets; as far as making the files executable, that > would be up to the author to make happen as they wish -- issues with > startup time would not be relevant to javadoc itself. Note that by > suggesting that the source files should be in their own source tree, it > would be up to the author to provide any additional infrastructure to > compile/test/run the examples, using the infrastructure of their choice > (i.e. Makefile/Ant/Maven/Graal/etc) > > I agree with your use cases, but the question common to both uses is, > would you want to also publish the entire source code for the files > containing the snippets ... and would that affect how you would want to > identify the snippets within the source files? > > -- Jon > On 1/20/19 5:06 PM, Nir Lisker wrote: > > The compiled examples idea sounds appealing. Having recently gone over and > corrected many snippets for JavaFX controls I can see the usefulness of > having them be compile-able. My only worry is that it will require new > files just for a few lines of examples each. For example, we have a > 'controls' package with classes for Label, Button, TextField etc. We > provide an example or two for each control, where would we put these 30 > files? How do we not make them load with the classloader, which makes > startup time longer? > > >> If there is any discussion to be had at this point, I would say it is to >> understand the use cases. >> > > There are 2 use cases that immediately come to mind: > 1. A single block as shown in [1]. > 2. A broken down block where each segment has a short discussion, as in > [2] under Creating a TableView. > > - Nir > > [1] > https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/Accordion.html > [2] > https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/TableView.html > > On Sun, Jan 20, 2019 at 7:08 PM Jonathan Gibbons < > jonathan.gibbons at oracle.com> wrote: > >> Nir, >> >> We're not there yet; we're just at the brainstorming stage. There is >> nothing public at this point. >> >> Here are some of the high-level points. >> >> 1. As far as JLS/javac is concerned, there is nothing special about >> documentation comments: they are just instances of "/*...*/" comments, >> which means that we will never be able to support literal unescaped use of >> "*/" within a comment. >> >> 2. For the standard doclet, there is a syntactic assumption about `@` at >> the beginning of a line, which is used to split the doc comment into an >> initial run of text, followed by the block tags. This is what causes >> problems for annotations in code samples. While we could modify that rule, >> it would mean we would have to do more detailed parsing of every comment, >> to determine the initial text and block tags. >> >> 3. While it is convenient to have "inline snippets" in doc comments, it >> is worth noting that there have been instances where snippets have been >> incorrect or invalid. Thus, there is an interest to support out-of-line >> snippets, taken from external source files, that can separately be compiled >> and/or tested. This suggests a tag like `{@example *args*}` or `{@snippet >> *args*}`. >> >> 4. For a tag like `{@snippet *args*}`, the discussion becomes, "what are >> the args". Two suggestions are: the name of a method whose body to include, >> or a range of text between markers, given in comments. Either could work, >> but then the discussion turns to the use cases. Is this just about snippets >> to include in the doc comment? Some have suggested that it would be worth >> being able to link to a copy of the complete source file in the generated >> documentation, for a big picture example of how to use an API. If the >> entire source is to be copied to somewhere in the documentation, then the >> issue of what delimiters to use for the inline snippet becomes more >> significant: do you want to see the markers, do you want to have to >> structure the source to arrange for suitable method boundaries, etc. >> >> 5. Some have suggested migrating towards the use of Markdown to replace >> the use of HTML in doc comments. While Markdown would give us a >> new/different way to solve the `<pre>{@code...` problem, it would not solve >> the issues outlined in any of the preceding discussion. >> >> If there is any discussion to be had at this point, I would say it is to >> understand the use cases. Is this about being able to include multiple >> small mostly-unrelated snippets of code, such as a few lines of code to >> give examples of how to use methods in an API, without necessarily being >> able to also include the entire source file somewhere, or is this about >> being able to write a high level narrative description, with selected >> snippets, of a complete working example program? >> >> -- Jon >> On 1/19/19 7:38 PM, Nir Lisker wrote: >> >> Hi Jon, >> >> Is any relevant material (discussion/prototype etc.) available to the >> public or are you not there yet? >> >> - Nir >> >> On Sat, Jan 19, 2019 at 12:37 AM Jonathan Gibbons < >> jonathan.gibbons at oracle.com> wrote: >> >>> Nir, >>> >>> There are some fundamental reasons why it is not possible to all of what >>> you suggest in the way you suggest (i.e. using raw string literals) For >>> the most obvious example, albeit a bit of an obscure case, would be a >>> raw string literal containing a /*...*/ comment. Similar problems apply >>> to the appearance of `@` which already has an existing meaning in >>> documentation comments. >>> >>> That being said, we are already investigating better ways to include >>> code samples and snippets in documentation comments, perhaps by being >>> able to insert code from a "nearby" source file, which would have the >>> advantage that (separately) the source file could itself be compiled to >>> ensure that it is syntactically correct. >>> >>> -- Jon >>> >>> >>> On 01/18/2019 02:08 PM, Nir Lisker wrote: >>> > Hi, >>> > >>> > I sent am email to amber-dev about the possibility of using Raw String >>> > Literals in JavaDoc [1]. I was sent here and told there was some >>> > discussion in this area. Would what I describe in [1] be possible in >>> > some form? >>> > >>> > Thanks, >>> > Nir >>> > >>> > [1] >>> > >>> https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html >>> >>> -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190124/a39ff7a6/attachment.html> From jonathan.gibbons at oracle.com Fri Jan 25 01:24:05 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 24 Jan 2019 17:24:05 -0800 Subject: RFR: 8215307: Pages do not have <h1> Message-ID: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> This is a fix for the long-standing problems concerning "gaps" (and related problems) in the headings (h1..h6 tags) in generated pages, that show up as accessibility issues. The problem was initially reported in the context of <h1> being missing from the documentation pages for type declarations. In the course of the work, an additional problem was discovered in the set of headings used in the serialized-form page. This fix should address all such problems. The fix comes in various parts. src/ changes ... 1. Most headings are generated using constants defined in a poorly-named class called HtmlConstants, in a poorly-chosen package (html.markup.) The constants are not very well defined, and it is hard to determine which constant should be used in which context. In particular, there are cases where the same constant is used in different contexts that should require different heading levels, and that helps contribute to the root cause of the problem. So, the constants are moved and reorganized into a new class specifically for heading constants (Headings.java), using nested classes to group the constants for each page. There are two notable nested classes, one for type declarations and another for the serialized-form page, which are the two kinds of pages with the most complex heading structure, and (not surprisingly) the most bugs.? Additional nested classes are added for other notable contexts, even if they only have a singleton entry. This will allow those contexts to be extended if the need arises. Within the Headings.TypeDeclaration class, the headings are adjusted to start from h1 instead of h2, which is the root of the fix to the issue. Iwent back and forth on the naming of the constants ... should they end in _HEADING or not? I tries both with and without. Right now, I left the names long; it works OK. 2. With the headings removed from HtmlConstants, the remaining constants are mostly a set of "marker comments" and a single constant for the default charset. The constant for the default charset is moved to the one class where it is used (HtmlConfiguration), leaving the HtmlConstants file to be renamed to MarkerComments.java, since that is all that remain. 3. Most of the remaining changes in the src/ directory are just updates to use the new reorganized Headings. There was one complication that occurred in two files, where the sequence of headings depended on whether or not the user provided options on the command line! Both instances are in files related to the "Frames" feature, which is scheduled for removal soon, and so I just "hacked" a solution to use the right header depending on the circumstances. If we were not planning to remove support for frames, it might have been worth figuring a different solution to the generated output, but that did not seem like a worthwhile effort. test/ changes ... As was to be expected, changing the headings for type declarations broke a number of tests which included a heading as part of their golden output. Since it is not easy to discern the correct values in all cases in all files just by looking at the fragments of code, the dominant most important test is the first change in JavadocTester, to globally enable by default the recently added accessibility checker, which checks for missing headings.? With that check enabled, it was possible to iterate between fixing tests and fixing source code, to ensure that there are no longer any missing headings. While in JavadocTester, I did some cosmetic cleanup to the doc comments in that file. One problem area was the Serialized Form page, which was visibly OK on the screen, but structurally bad when you looked at the headings. (i.e. CSS was papering over the problem.) For this problem, it was useful to add another new feature to JavadocTester, to print out a filtered view of just the headings in a page. While the check for missing headings finds many problems, it doesn't find all. For example, if a page should have headings "H1 H2 H3" but actually has "H1 H2 H2" that will pass the "missing headings" test, even though the page is logically incorrect. The new ShowHeadings feature in JavadocTester helps to expose such problems by making it easy to (manually) verify the hierarchy of headings in a file. stylesheet changes ... The standard javadoc stylesheet uses almost-global settings for the font size and style of the 6 levels of headings. For the most part, these settings are used across all pages. (The exceptions are for the index files in the frames feature, which, as has already been noted, is going away sometime soon.)? The one additional visual cue for headings is the occasional use of a grey background for headings, which does vary depending on the context (i.e. page and heading-level.) The only change to the stylesheet at this point is to ensure that the grey background is used in the same positions as before ... typically for the heading that precedes a list of elements, such as a list of members in a class. The global settings for the font size and style are (intentionally) not modified in this changeset.? This means that the appearance of headings is generally consistent across all kinds of pages, although there are some visual changes in some of the generated pages . We could revisit that if necessary to get the same appearance as before, meaning that we would be visually inconsistent between different kinds of pages. If so, that should be a different cleanup task. I note that it would be a CSS-only task; I believe there is enough info in the HTML that no further changes to the generated HTML would be necessary. In various discussions regarding this feature, concerns were expressed that "<h1> is too big".? Given the existing definitions within the standard stylesheet, this does not seem to be a problem in practice. Review tips: * Start by looking at how HtmlConstants was converted into Headings and MarkerComments * For tests, start by looking at JavadocTester * For the mundane changes to tests, you may find it worth looking at the patch files instead of the side-by-side diffs -- Jon JBS: https://bugs.openjdk.java.net/browse/JDK-8215307 Webrev: http://cr.openjdk.java.net/~jjg/8215307/webrev.00/ From christoph.langer at sap.com Fri Jan 25 08:10:57 2019 From: christoph.langer at sap.com (Langer, Christoph) Date: Fri, 25 Jan 2019 08:10:57 +0000 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 Message-ID: <2768da62bd2842b0963252509f839fe8@sap.com> Hi, it seems that after JDK-8217034, the test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java is broken. The fix looks trivial, please review: Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ Thanks Christoph -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/2105a3b4/attachment.html> From christoph.langer at sap.com Fri Jan 25 10:12:36 2019 From: christoph.langer at sap.com (Langer, Christoph) Date: Fri, 25 Jan 2019 10:12:36 +0000 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 Message-ID: <261a14951b734d34bfe2cf773e89eaa5@sap.com> Hi, it seems that after JDK-8217034, the test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java is broken. The fix looks trivial, please review: Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ BTW: Looking at the generated Javadoc for method pkg.B::externalLink, one can see that the output for the "see also" section does not look optimal. The line of "java.net.URISyntaxException" starts with a comma which can't be avoided. Don't know if this merits a JBS issue or it is a corner case which is hardly ever used... Thanks Christoph -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/818a0645/attachment.html> From martin.desruisseaux at geomatys.com Fri Jan 25 09:41:14 2019 From: martin.desruisseaux at geomatys.com (Martin Desruisseaux) Date: Fri, 25 Jan 2019 10:41:14 +0100 Subject: RFR: 8215307: Pages do not have <h1> In-Reply-To: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> References: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> Message-ID: <3420ba45-540e-7f63-0d90-7380d82282c4@geomatys.com> Hello Jonathan. Thanks for all this work. I was wondering if the use of <h1>, <h2>, etc. nested inside <section> has been considered for simplifying the heading ranks? If I understood [1] and [2] correctly, the following are semantically identical in HTML5: <h1>XXX</h1> <section> <h2>YYY</h2> <section> <h3>ZZZ</h3> and <h1>XXX</h1> <section> <h1>YYY</h1> <section> <h1>ZZZ</h1> Wouldn't the use of <section> allows to reset the <h#> counting to 1 for that section, which would free the developer to care about what was the rank of last <h#> element? If each field and method is in its own <section>, wouldn't it allow developers to use <h1>, <h2>, etc. in their javadoc for each field/method? ??? Martin [1] https://www.w3.org/TR/2011/WD-html5-author-20110809/headings-and-sections.html#headings-and-sections [2] https://www.w3.org/TR/2011/WD-html5-author-20110809/the-h1-h2-h3-h4-h5-and-h6-elements.html#rank -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/7f4d5e80/attachment.html> From jonathan.gibbons at oracle.com Fri Jan 25 16:30:06 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 25 Jan 2019 08:30:06 -0800 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 In-Reply-To: <2768da62bd2842b0963252509f839fe8@sap.com> References: <2768da62bd2842b0963252509f839fe8@sap.com> Message-ID: <cf582947-b8dc-420b-2e8c-a96388c46aca@oracle.com> Christoph, Thanks for reporting the problem. The issue may be real, but at first glance, your fix looks incorrect. The test is specifically about testing a "<a href...>" and so it is incorrect to replace it to the more conventional "@see ..." tag. I will investigate in more detail later today. -- Jon On 1/25/19 12:10 AM, Langer, Christoph wrote: > > Hi, > > it seems that after JDK-8217034, the test > langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java is > broken. The fix looks trivial, please review: > > Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 > > Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ > <http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/> > > Thanks > > Christoph > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/7a0c34cc/attachment.html> From jonathan.gibbons at oracle.com Fri Jan 25 16:39:20 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 25 Jan 2019 08:39:20 -0800 Subject: RFR: 8215307: Pages do not have <h1> In-Reply-To: <3420ba45-540e-7f63-0d90-7380d82282c4@geomatys.com> References: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> <3420ba45-540e-7f63-0d90-7380d82282c4@geomatys.com> Message-ID: <7e45169f-691d-eba9-720d-8496ee47a297@oracle.com> Martin, Interesting .. The references you give are in documents labeled "Working Draft", so I'd be looking to see more definitive versions of those pages. In addition, the issues are for accessibility and screen readers (i.e. WAI-ARIA), which tend to have more strict requirements than plain HTML5. -- Jon On 1/25/19 1:41 AM, Martin Desruisseaux wrote: > > Hello Jonathan. Thanks for all this work. I was wondering if the use > of <h1>, <h2>, etc. nested inside <section> has been considered for > simplifying the heading ranks? If I understood [1] and [2] correctly, > the following are semantically identical in HTML5: > > <h1>XXX</h1> > <section> > <h2>YYY</h2> > <section> > <h3>ZZZ</h3> > > and > > <h1>XXX</h1> > <section> > <h1>YYY</h1> > <section> > <h1>ZZZ</h1> > > Wouldn't the use of <section> allows to reset the <h#> counting to 1 > for that section, which would free the developer to care about what > was the rank of last <h#> element? If each field and method is in its > own <section>, wouldn't it allow developers to use <h1>, <h2>, etc. in > their javadoc for each field/method? > > ??? Martin > > [1]https://www.w3.org/TR/2011/WD-html5-author-20110809/headings-and-sections.html#headings-and-sections > [2]https://www.w3.org/TR/2011/WD-html5-author-20110809/the-h1-h2-h3-h4-h5-and-h6-elements.html#rank > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/a317dec8/attachment-0001.html> From christoph.langer at sap.com Fri Jan 25 16:38:49 2019 From: christoph.langer at sap.com (Langer, Christoph) Date: Fri, 25 Jan 2019 16:38:49 +0000 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 In-Reply-To: <cf582947-b8dc-420b-2e8c-a96388c46aca@oracle.com> References: <2768da62bd2842b0963252509f839fe8@sap.com> <cf582947-b8dc-420b-2e8c-a96388c46aca@oracle.com> Message-ID: <b5d9d82c1ed64c9fa4e33d68d9cd0c72@sap.com> Hi Jon, maybe the link check just has to be skipped for the URISyntaxException. The problem seems to be that the (hardcoded) link at this place links to a location that does not exist ? but this is checked. So, looking forward to your fix ?? Thanks & Best regards Christoph From: Jonathan Gibbons <jonathan.gibbons at oracle.com> Sent: Freitag, 25. Januar 2019 17:30 To: Langer, Christoph <christoph.langer at sap.com>; javadoc-dev at openjdk.java.net Cc: Zeller, Arno <arno.zeller at sap.com> Subject: Re: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 Christoph, Thanks for reporting the problem. The issue may be real, but at first glance, your fix looks incorrect. The test is specifically about testing a "<a href...>" and so it is incorrect to replace it to the more conventional "@see ..." tag. I will investigate in more detail later today. -- Jon On 1/25/19 12:10 AM, Langer, Christoph wrote: Hi, it seems that after JDK-8217034, the test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java is broken. The fix looks trivial, please review: Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ Thanks Christoph -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/1ce68e7f/attachment.html> From jonathan.gibbons at oracle.com Fri Jan 25 17:04:24 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 25 Jan 2019 09:04:24 -0800 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 In-Reply-To: <b5d9d82c1ed64c9fa4e33d68d9cd0c72@sap.com> References: <2768da62bd2842b0963252509f839fe8@sap.com> <cf582947-b8dc-420b-2e8c-a96388c46aca@oracle.com> <b5d9d82c1ed64c9fa4e33d68d9cd0c72@sap.com> Message-ID: <8ced8915-15d9-2315-193e-d9a67ff7354d@oracle.com> Thanks for the suggestion. If that is sufficient for now, that may be the best solution. Maybe there's a future-RFE to exclude specific references from the link checker. -- Jon On 1/25/19 8:38 AM, Langer, Christoph wrote: > > Hi Jon, > > maybe the link check just has to be skipped for the > URISyntaxException. The problem seems to be that the (hardcoded) link > at this place links to a location that does not exist ? but this is > checked. So, looking forward to your fix ?? > > Thanks & Best regards > > Christoph > > *From:*Jonathan Gibbons <jonathan.gibbons at oracle.com> > *Sent:* Freitag, 25. Januar 2019 17:30 > *To:* Langer, Christoph <christoph.langer at sap.com>; > javadoc-dev at openjdk.java.net > *Cc:* Zeller, Arno <arno.zeller at sap.com> > *Subject:* Re: RFR (S): 8217773: Test > langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java > fails after JDK-8217034 > > Christoph, > > Thanks for reporting the problem. > > The issue may be real, but at first glance, your fix looks incorrect. > The test is specifically about testing a "<a href...>" and so it is > incorrect to replace it to the more conventional "@see ..." tag. > > I will investigate in more detail later today. > > -- Jon > > On 1/25/19 12:10 AM, Langer, Christoph wrote: > > Hi, > > it seems that after JDK-8217034, the test > langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java > is broken. The fix looks trivial, please review: > > Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 > <https://bugs.openjdk.java.net/browse/JDK-8217773> > > Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ > <http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/> > > Thanks > > Christoph > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/59a856dd/attachment.html> From jonathan.gibbons at oracle.com Fri Jan 25 21:46:40 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 25 Jan 2019 13:46:40 -0800 Subject: RFR: 8215307: Pages do not have <h1> In-Reply-To: <3420ba45-540e-7f63-0d90-7380d82282c4@geomatys.com> References: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> <3420ba45-540e-7f63-0d90-7380d82282c4@geomatys.com> Message-ID: <4afd93ac-b058-3f73-d103-4b2b61e9cc83@oracle.com> Martin, Thank you for your interest in this area; sometimes it's good to know that other folk care about this sort of stuff as well ;-) There are a number of different aspects to consider here. 1. Your suggestion presupposes HTML 5. As of right now, javadoc (or more accurately, the standard doclet) still supports HTML 4 ... but that being said, work is underway to remove support for HTML 4. javadoc has given warnings for a while, and it's finally time to remove it. Suggestions like yours are another reason why it is time to remove support for HTML 4. [Aside: I note the CSR to remove HTML 4, JDK-8215578, has just now been approved, so we will soon be proceeding with the actual removal.] 2. This issue (pages do not have <h1>) is part of the overall ongoing campaign to fix accessibility issues in generated javadoc, both in general and in the JDK API in particular. It's the latest in a series of updates over the past few years, including improved tables, improved use of regions, and so on. This means that we want to abide by WCAG standards as well as HTML 5 standards. 3. Your links are for a Working Draft. This seems to be an equivalent page in the latest version: https://www.w3.org/TR/html5/sections.html#headings-and-sections That page does not have the "every <section> has an <h1>" example. It does have the following text, which ties the heading rank to the nesting level: /Sections may contain headings of a //rank <https://www.w3.org/TR/html5/sections.html#rank>//equal to their section nesting level. Authors should use headings of the appropriate //rank <https://www.w3.org/TR/html5/sections.html#rank>//for the section?s nesting level./ Here's a relevant page from WCAG: https://www.w3.org/TR/WCAG20-TECHS/G141.html It says: /To facilitate navigation and understanding of overall document structure, authors should use headings that are properly nested (e.g., h1 followed by h2, h2 followed by h2 or h3, h3 followed by h3 or h4, etc.)./ 4. This particular bug is (just) about changing the javadoc-generated headings. It doesn't enforce particular headings within comments, although it does encourage particular heading levels if doclint is enabled. You might reasonably surmise that as the overall work moves forward, we will need to fix up doclint, and the headings in JDK API doc comments, to achieve our goals in this area. That is "coming soon"; this review is just the first step, for the javadoc/doclet part of the work. 5. It has been suggested that javadoc should allow headings to start at h1 in each comment, and that javadoc should adjust them as necessary. For my part, I think that would be a bad idea, because it could lead to unexpected differences between the headings in the comments and entries in the style sheet. It's not good if the user wrote <h1> or <h2> in their comment, and javadoc rewrites it to <h3> or <h4>. --- Finally, I welcome any additional input or interpretation of the prevailing existing standards in this area! -- Jon On 01/25/2019 01:41 AM, Martin Desruisseaux wrote: > > Hello Jonathan. Thanks for all this work. I was wondering if the use > of <h1>, <h2>, etc. nested inside <section> has been considered for > simplifying the heading ranks? If I understood [1] and [2] correctly, > the following are semantically identical in HTML5: > > <h1>XXX</h1> > <section> > <h2>YYY</h2> > <section> > <h3>ZZZ</h3> > > and > > <h1>XXX</h1> > <section> > <h1>YYY</h1> > <section> > <h1>ZZZ</h1> > > Wouldn't the use of <section> allows to reset the <h#> counting to 1 > for that section, which would free the developer to care about what > was the rank of last <h#> element? If each field and method is in its > own <section>, wouldn't it allow developers to use <h1>, <h2>, etc. in > their javadoc for each field/method? > > ??? Martin > > [1]https://www.w3.org/TR/2011/WD-html5-author-20110809/headings-and-sections.html#headings-and-sections > [2]https://www.w3.org/TR/2011/WD-html5-author-20110809/the-h1-h2-h3-h4-h5-and-h6-elements.html#rank > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/ba7a6234/attachment-0001.html> From jonathan.gibbons at oracle.com Fri Jan 25 23:38:11 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 25 Jan 2019 15:38:11 -0800 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 In-Reply-To: <cf582947-b8dc-420b-2e8c-a96388c46aca@oracle.com> References: <2768da62bd2842b0963252509f839fe8@sap.com> <cf582947-b8dc-420b-2e8c-a96388c46aca@oracle.com> Message-ID: <7f733bd5-aaa3-a10f-ed69-40bbd94f4b06@oracle.com> Christoph, and other javadoc Reveiwers, Thanks again for reporting the problem. It went unnoticed here because it is not common to run tests with proxy access through the corporate firewall, and this test quietly skips one of its subtests when it cannot access an external resource. I was able to reproduce your results by running the test with proxies set up. There are two possible fixes to the problem. One is to disable the "missing file" check, and the other to to change the name of the target in the link to a nearby file that does exist.? Here are the two patches, :::::::::::::: fix1.patch :::::::::::::: diff -r 090395557398 test/langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java --- a/test/langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java Fri Jan 25 14:28:43 2019 -0800 +++ b/test/langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java Fri Jan 25 15:13:43 2019 -0800 @@ -116,6 +116,7 @@ ???????? String apiURL = "http://docs.oracle.com/en/java/javase/11/docs/api"; ???????? String outRedirect = "outRedirect"; +??????? setAutomaticCheckLinks(false); // The example code has toy/bad links ???????? javadoc("-d", outRedirect, ???????????????? "-html4", ???????????????? "-sourcepath", testSrc, @@ -128,6 +129,7 @@ ???????? checkOutput("pkg/C.html", true, ???????????????? "<a href=\"" + apiURL + "/java.base/java/lang/Object.html?is-external=true\" " ???????????????????????? + "title=\"class or interface in java.lang\" class=\"externalLink\">Object</a>"); +??????? setAutomaticCheckLinks(true); // re-enable checks ???? } ???? private Path libApi = Path.of("libApi"); :::::::::::::: fix2.patch :::::::::::::: diff -r 090395557398 test/langtools/jdk/javadoc/doclet/testLinkOption/pkg/B.java --- a/test/langtools/jdk/javadoc/doclet/testLinkOption/pkg/B.java Fri Jan 25 14:28:43 2019 -0800 +++ b/test/langtools/jdk/javadoc/doclet/testLinkOption/pkg/B.java Fri Jan 25 15:15:18 2019 -0800 @@ -60,7 +60,7 @@ ???? * Resource Identifiers (URI): Generic Syntax</i></a>, <br><a ???? * href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC 2732: Format for ???? * Literal IPv6 Addresses in URLs</i></a>, <br><a -??? * href="URISyntaxException.html">URISyntaxException</a> +??? * href="C.html">A nearby file</a> ???? */ ??? public void externalLink() {} ?} Of the two, I prefer the second on principle, because having worked to enable automatic link checking as much as possible, I don't like disabling it anywhere. The one wrinkle here is that the change impacts another test in the same directory, but that one is easy to fix up, and to then enable the link checking in that part of that test.? That additional fix is included in the webrev. http://cr.openjdk.java.net/~jjg/8217773/webrev.00/ -- Jon On 01/25/2019 08:30 AM, Jonathan Gibbons wrote: > > Christoph, > > Thanks for reporting the problem. > > The issue may be real, but at first glance, your fix looks incorrect. > The test is specifically about testing a "<a href...>" and so it is > incorrect to replace it to the more conventional "@see ..." tag. > > I will investigate in more detail later today. > > -- Jon > > On 1/25/19 12:10 AM, Langer, Christoph wrote: >> >> Hi, >> >> it seems that after JDK-8217034, the test >> langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java is >> broken. The fix looks trivial, please review: >> >> Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 >> >> Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ >> <http://cr.openjdk.java.net/%7Eclanger/webrevs/8217773.0/> >> >> Thanks >> >> Christoph >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/fc43f6cd/attachment.html> From martin.desruisseaux at geomatys.com Sat Jan 26 10:45:52 2019 From: martin.desruisseaux at geomatys.com (Martin Desruisseaux) Date: Sat, 26 Jan 2019 11:45:52 +0100 Subject: RFR: 8215307: Pages do not have <h1> In-Reply-To: <4afd93ac-b058-3f73-d103-4b2b61e9cc83@oracle.com> References: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> <3420ba45-540e-7f63-0d90-7380d82282c4@geomatys.com> <4afd93ac-b058-3f73-d103-4b2b61e9cc83@oracle.com> Message-ID: <bdeace62-0bf1-7b58-c992-3871b35d19bf@geomatys.com> Hello Johathan Le 25/01/2019 ? 22:46, Jonathan Gibbons a ?crit?: > 3. Your links are for a Working Draft. This seems to be an equivalent > page in the latest version: > > https://www.w3.org/TR/html5/sections.html#headings-and-sections > Thanks for the link to relevant W3C pages. I did not noticed that the final documents differed from the draft in this aspect. Indeed, my proposal can not apply anymore in the context of latest specification. > 4. This particular bug is (just) about changing the javadoc-generated > headings. It doesn't enforce particular headings within comments, > although it does encourage particular heading levels if doclint is > enabled. You might reasonably surmise that as the overall work moves > forward, we will need to fix up doclint, and the headings in JDK API > doc comments, to achieve our goals in this area. That is "coming > soon"; this review is just the first step, for the javadoc/doclet part > of the work. Understood, thanks for this effort! > 5. It has been suggested that javadoc should allow headings to start > at h1 in each comment, and that javadoc should adjust them as > necessary. For my part, I think that would be a bad idea, because it > could lead to unexpected differences between the headings in the > comments and entries in the style sheet. It's not good if the user > wrote <h1> or <h2> in their comment, and javadoc rewrites it to <h3> > or <h4>. > On the other hand, requiring developers to start heading with <h3> or <h4> in their comments is error-prone. I guess that the alternative of defining a new Javadoc tag has already been explored? Note exactly about <h1> but somewhat related, if we can leverage HTML5 (i.e. HTML4 support is abandoned), what about enclosing each field, constructor and method definition in a HTML5 <details> and <summary> elements? With the method signature in <summary> and the comment body in <details>. This would allow the reader to show only the method details (s)he wants to see. ??? Martin From jonathan.gibbons at oracle.com Sat Jan 26 17:00:51 2019 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Sat, 26 Jan 2019 09:00:51 -0800 Subject: RFR: 8215307: Pages do not have <h1> In-Reply-To: <bdeace62-0bf1-7b58-c992-3871b35d19bf@geomatys.com> References: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> <3420ba45-540e-7f63-0d90-7380d82282c4@geomatys.com> <4afd93ac-b058-3f73-d103-4b2b61e9cc83@oracle.com> <bdeace62-0bf1-7b58-c992-3871b35d19bf@geomatys.com> Message-ID: <ea862bd2-df31-347b-7f36-4656425ff7aa@oracle.com> On 1/26/19 2:45 AM, Martin Desruisseaux wrote: > Hello Johathan > > Le 25/01/2019 ? 22:46, Jonathan Gibbons a ?crit?: > >> 3. Your links are for a Working Draft. This seems to be an equivalent >> page in the latest version: >> >> https://www.w3.org/TR/html5/sections.html#headings-and-sections >> > Thanks for the link to relevant W3C pages. I did not noticed that the > final documents differed from the draft in this aspect. Indeed, my > proposal can not apply anymore in the context of latest specification. > > >> 4. This particular bug is (just) about changing the javadoc-generated >> headings. It doesn't enforce particular headings within comments, >> although it does encourage particular heading levels if doclint is >> enabled. You might reasonably surmise that as the overall work moves >> forward, we will need to fix up doclint, and the headings in JDK API >> doc comments, to achieve our goals in this area. That is "coming >> soon"; this review is just the first step, for the javadoc/doclet part >> of the work. > Understood, thanks for this effort! > > >> 5. It has been suggested that javadoc should allow headings to start >> at h1 in each comment, and that javadoc should adjust them as >> necessary. For my part, I think that would be a bad idea, because it >> could lead to unexpected differences between the headings in the >> comments and entries in the style sheet. It's not good if the user >> wrote <h1> or <h2> in their comment, and javadoc rewrites it to <h3> >> or <h4>. >> > On the other hand, requiring developers to start heading with <h3> or > <h4> in their comments is error-prone. I guess that the alternative of > defining a new Javadoc tag has already been explored? Yes and no.? Yes, it has been talked about; no, it has not been discussed enough for us to pursue it at this point. I have been anticipating that the next step is to update the javadoc doc comment specification [1] to define the HTML headings to use in comments. That may be the time to consider the provision of new tags. But, even if we define javadoc tags that can be used, we still have to accept HTML headings in the comment, and specify their effect. [1] https://docs.oracle.com/javase/10/docs/specs/doc-comment-spec.html > > Note exactly about <h1> but somewhat related, if we can leverage HTML5 > (i.e. HTML4 support is abandoned), what about enclosing each field, > constructor and method definition in a HTML5 <details> and <summary> > elements? With the method signature in <summary> and the comment body in > <details>. This would allow the reader to show only the method details > (s)he wants to see. It is definitely the case that it will be easier to leverage new features in HTML 5 when we drop the need to support both versions. I've not yet played with <details> and <summary>.? The one thing I will note is that these terms do not correspond with the way these terms are presented in the generated documentation. That's not in itself a problem; just a caution to those looking at these tags. One similar/related change that came to mind while debugging recent changes is that we use <div> a lot in the output, and that in a number of places, we could reasonably use <section> instead.? I suspect we should start keeping a list of possible enhancements. -- Jon > > ??? Martin > > From priya.lakshmi.muthuswamy at oracle.com Mon Jan 28 04:44:45 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 28 Jan 2019 10:14:45 +0530 Subject: RFR: 8215577: Remove javadoc support for HTML 4 Message-ID: <99dbda8f-d5eb-420d-86e4-1e89ace786bb@oracle.com> Hi, Kindly review the changes for the removal for html4 support from javadoc. JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ Thanks, Priya -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190128/eb6209b8/attachment.html> From priya.lakshmi.muthuswamy at oracle.com Mon Jan 28 09:48:26 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 28 Jan 2019 15:18:26 +0530 Subject: RFR: 8215577: Remove javadoc support for HTML 4 In-Reply-To: <99dbda8f-d5eb-420d-86e4-1e89ace786bb@oracle.com> References: <99dbda8f-d5eb-420d-86e4-1e89ace786bb@oracle.com> Message-ID: <66670def-6dfc-d685-699e-e4ba2519efe1@oracle.com> forgot to mention CSR . JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ CSR : https://bugs.openjdk.java.net/browse/JDK-8215578 Thanks, Priya On 1/28/2019 10:14 AM, Priya Lakshmi Muthuswamy wrote: > > Hi, > > Kindly review the changes for the removal for html4 support from javadoc. > JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 > webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ > > Thanks, > Priya > -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190128/63de641e/attachment.html> From hannes.wallnoefer at oracle.com Mon Jan 28 12:26:08 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Mon, 28 Jan 2019 13:26:08 +0100 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 In-Reply-To: <261a14951b734d34bfe2cf773e89eaa5@sap.com> References: <261a14951b734d34bfe2cf773e89eaa5@sap.com> Message-ID: <34651011-16C3-4D2D-8F25-42F03582982F@oracle.com> Hi Christoph, Looks good to me and fixes the problem. I?m not sure whether the purpose of the original link was to have a verbatim <a> HTML tag, but that seems to be covered by the other links in that test. Hannes > Am 25.01.2019 um 11:12 schrieb Langer, Christoph <christoph.langer at sap.com>: > > Hi, > > it seems that after JDK-8217034, the test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java is broken. The fix looks trivial, please review: > > Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 > Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ > > BTW: Looking at the generated Javadoc for method pkg.B::externalLink, one can see that the output for the ?see also? section does not look optimal. The line of ?java.net.URISyntaxException? starts with a comma which can?t be avoided. Don?t know if this merits a JBS issue or it is a corner case which is hardly ever used? > > Thanks > Christoph From hannes.wallnoefer at oracle.com Mon Jan 28 12:31:13 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Mon, 28 Jan 2019 13:31:13 +0100 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 In-Reply-To: <34651011-16C3-4D2D-8F25-42F03582982F@oracle.com> References: <261a14951b734d34bfe2cf773e89eaa5@sap.com> <34651011-16C3-4D2D-8F25-42F03582982F@oracle.com> Message-ID: <F468FC7E-9FEF-48BA-9548-1CA1EB09153E@oracle.com> Sorry, Sent this without seeing Jon?s more thorough replies, which showed as a separate thread in my mail reader. Please ignore. Hannes > Am 28.01.2019 um 13:26 schrieb Hannes Walln?fer <hannes.wallnoefer at oracle.com>: > > Hi Christoph, > > Looks good to me and fixes the problem. I?m not sure whether the purpose of the original link was to have a verbatim <a> HTML tag, but that seems to be covered by the other links in that test. > > Hannes > >> Am 25.01.2019 um 11:12 schrieb Langer, Christoph <christoph.langer at sap.com>: >> >> Hi, >> >> it seems that after JDK-8217034, the test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java is broken. The fix looks trivial, please review: >> >> Bug: https://bugs.openjdk.java.net/browse/JDK-8217773 >> Webrev: http://cr.openjdk.java.net/~clanger/webrevs/8217773.0/ >> >> BTW: Looking at the generated Javadoc for method pkg.B::externalLink, one can see that the output for the ?see also? section does not look optimal. The line of ?java.net.URISyntaxException? starts with a comma which can?t be avoided. Don?t know if this merits a JBS issue or it is a corner case which is hardly ever used? >> >> Thanks >> Christoph > From hannes.wallnoefer at oracle.com Mon Jan 28 15:18:28 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Mon, 28 Jan 2019 16:18:28 +0100 Subject: RFR: 8215577: Remove javadoc support for HTML 4 In-Reply-To: <66670def-6dfc-d685-699e-e4ba2519efe1@oracle.com> References: <99dbda8f-d5eb-420d-86e4-1e89ace786bb@oracle.com> <66670def-6dfc-d685-699e-e4ba2519efe1@oracle.com> Message-ID: <EE10A023-B252-44DE-AB72-763B6D3E9B26@oracle.com> Hi Priya, In quite a few places where Table#setSummary used to be called, the summary string for that call is still computed or at least passed around without being used. I think this is the case for all classes implementing AbstractMemberWriter#createSummaryTable(): AnnotationTypeFieldWriterImpl AnnotationTypeRequiredMemberWriterImpl (method getTableSummary() is never used) ConstructorWriterImpl EnumConstantWriterImpl FieldWriterImpl MethodWriterImpl NestedClassWriterImpl PropertyWriterImpl There may be a few other passing around summary arguments that aren?t used. Otherwise your patch looks good to me. Hannes > Am 28.01.2019 um 10:48 schrieb Priya Lakshmi Muthuswamy <priya.lakshmi.muthuswamy at oracle.com>: > > forgot to mention CSR . > JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 > webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ > CSR : https://bugs.openjdk.java.net/browse/JDK-8215578 > > Thanks, > Priya > On 1/28/2019 10:14 AM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review the changes for the removal for html4 support from javadoc. >> JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 >> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ >> >> Thanks, >> Priya >> From christoph.langer at sap.com Mon Jan 28 07:03:39 2019 From: christoph.langer at sap.com (Langer, Christoph) Date: Mon, 28 Jan 2019 07:03:39 +0000 Subject: RFR (S): 8217773: Test langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java fails after JDK-8217034 In-Reply-To: <7f733bd5-aaa3-a10f-ed69-40bbd94f4b06@oracle.com> References: <2768da62bd2842b0963252509f839fe8@sap.com> <cf582947-b8dc-420b-2e8c-a96388c46aca@oracle.com> <7f733bd5-aaa3-a10f-ed69-40bbd94f4b06@oracle.com> Message-ID: <4568fbb2cb94453a97254b045d80fb56@sap.com> Hi Jon, > Thanks again for reporting the problem. It went unnoticed here because it is > not common to run tests with proxy access through the corporate firewall, > and this test quietly skips one of its subtests when it cannot access an > external resource. I was able to reproduce your results by running the test > with proxies set up. Ah, that explains it. We're obviously having an environment with outbound internet access in our CI infrastructure where the test failed. And it reproduced on my desktop, too, since it also has connectivity. > There are two possible fixes to the problem. One is to disable the "missing > file" check, and the other to to change the name of the target in the link to a > nearby file that does exist. Here are the two patches, > Of the two, I prefer the second on principle, because having worked to > enable automatic link checking as much as possible, I don't like disabling it > anywhere. The one wrinkle here is that the change impacts another test in > the same directory, but that one is easy to fix up, and to then enable the link > checking in that part of that test. That additional fix is included in the > webrev. I agree. > http://cr.openjdk.java.net/~jjg/8217773/webrev.00/ Looks good. I tested this fix in both, the CI and my desktop. Reviewed. Thanks & Best regards Christoph From priya.lakshmi.muthuswamy at oracle.com Tue Jan 29 06:22:10 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Tue, 29 Jan 2019 11:52:10 +0530 Subject: RFR: 8215577: Remove javadoc support for HTML 4 In-Reply-To: <EE10A023-B252-44DE-AB72-763B6D3E9B26@oracle.com> References: <99dbda8f-d5eb-420d-86e4-1e89ace786bb@oracle.com> <66670def-6dfc-d685-699e-e4ba2519efe1@oracle.com> <EE10A023-B252-44DE-AB72-763B6D3E9B26@oracle.com> Message-ID: <a62db6b0-2e7b-047e-c1d2-bbdba5693ede@oracle.com> Hi Hannes, Thanks for the review. I have removed the unused summary string computation from the code. webrev : http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.02/ Thanks, Priya On 1/28/2019 8:48 PM, Hannes Walln?fer wrote: > Hi Priya, > > In quite a few places where Table#setSummary used to be called, the summary string for that call is still computed or at least passed around without being used. I think this is the case for all classes implementing AbstractMemberWriter#createSummaryTable(): > > AnnotationTypeFieldWriterImpl > AnnotationTypeRequiredMemberWriterImpl (method getTableSummary() is never used) > ConstructorWriterImpl > EnumConstantWriterImpl > FieldWriterImpl > MethodWriterImpl > NestedClassWriterImpl > PropertyWriterImpl > > There may be a few other passing around summary arguments that aren?t used. > > Otherwise your patch looks good to me. > > Hannes > > >> Am 28.01.2019 um 10:48 schrieb Priya Lakshmi Muthuswamy <priya.lakshmi.muthuswamy at oracle.com>: >> >> forgot to mention CSR . >> JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 >> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ >> CSR : https://bugs.openjdk.java.net/browse/JDK-8215578 >> >> Thanks, >> Priya >> On 1/28/2019 10:14 AM, Priya Lakshmi Muthuswamy wrote: >>> Hi, >>> >>> Kindly review the changes for the removal for html4 support from javadoc. >>> JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 >>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ >>> >>> Thanks, >>> Priya >>> From hannes.wallnoefer at oracle.com Tue Jan 29 11:50:16 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Tue, 29 Jan 2019 12:50:16 +0100 Subject: RFR: 8215307: Pages do not have <h1> In-Reply-To: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> References: <df29b122-1371-ffec-ea83-8bd21fea3daf@oracle.com> Message-ID: <B6910695-7910-4A64-B2A3-579AE087751D@oracle.com> Hi Jon, The patch looks good to me. Regarding changes (or lack of changes) in the stylesheet: I think it is ok to not adapt header font size, but there is a font-style:italic rule for h3 headers which I think is problematic. That rule has moved from details heading to member heading in type pages, except that it is overwritten *sometimes* but not always by the following rule: ul.blockList ul.blockList ul.blockList li.blockList h3 { font-style:normal; } That rule for some reason does not apply to the last member in each category (i.e. the last field, constructor, method of a type), so that those member headers are displayed in italic font. I think the proper solution would be to move the font-style:italic rule from h3 to h2 (so summary and details headings would still be displayed in italic), but I?m not quite sure how that might affect other pages. Hannes > Am 25.01.2019 um 02:24 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>: > > This is a fix for the long-standing problems concerning "gaps" (and related problems) in the headings (h1..h6 tags) in generated pages, that show up as accessibility issues. > > The problem was initially reported in the context of <h1> being missing from the documentation pages for type declarations. In the course of the work, an additional problem was discovered in the set of headings used in the serialized-form page. This fix should address all such problems. > > The fix comes in various parts. > > src/ changes ... > > 1. Most headings are generated using constants defined in a poorly-named class called HtmlConstants, in a poorly-chosen package (html.markup.) The constants are not very well defined, and it is hard to determine which constant should be used in which context. In particular, there are cases where the same constant is used in different contexts that should require different heading levels, and that helps contribute to the root cause of the problem. So, the constants are moved and reorganized into a new class specifically for heading constants (Headings.java), using nested classes to group the constants for each page. There are two notable nested classes, one for type declarations and another for the serialized-form page, which are the two kinds of pages with the most complex heading structure, and (not surprisingly) the most bugs. Additional nested classes are added for other notable contexts, even if they only have a singleton entry. This will allow those contexts to be extended if the need arises. Within the Headings.TypeDeclaration class, the headings are adjusted to start from h1 instead of h2, which is the root of the fix to the issue. Iwent back and forth on the naming of the constants ... should they end in _HEADING or not? I tries both with and without. Right now, I left the names long; it works OK. > > 2. With the headings removed from HtmlConstants, the remaining constants are mostly a set of "marker comments" and a single constant for the default charset. The constant for the default charset is moved to the one class where it is used (HtmlConfiguration), leaving the HtmlConstants file to be renamed to MarkerComments.java, since that is all that remain. > > 3. Most of the remaining changes in the src/ directory are just updates to use the new reorganized Headings. There was one complication that occurred in two files, where the sequence of headings depended on whether or not the user provided options on the command line! Both instances are in files related to the "Frames" feature, which is scheduled for removal soon, and so I just "hacked" a solution to use the right header depending on the circumstances. If we were not planning to remove support for frames, it might have been worth figuring a different solution to the generated output, but that did not seem like a worthwhile effort. > > test/ changes ... > > As was to be expected, changing the headings for type declarations broke a number of tests which included a heading as part of their golden output. Since it is not easy to discern the correct values in all cases in all files just by looking at the fragments of code, the dominant most important test is the first change in JavadocTester, to globally enable by default the recently added accessibility checker, which checks for missing headings. With that check enabled, it was possible to iterate between fixing tests and fixing source code, to ensure that there are no longer any missing headings. > > While in JavadocTester, I did some cosmetic cleanup to the doc comments in that file. > > One problem area was the Serialized Form page, which was visibly OK on the screen, but structurally bad when you looked at the headings. (i.e. CSS was papering over the problem.) For this problem, it was useful to add another new feature to JavadocTester, to print out a filtered view of just the headings in a page. While the check for missing headings finds many problems, it doesn't find all. For example, if a page should have headings "H1 H2 H3" but actually has "H1 H2 H2" that will pass the "missing headings" test, even though the page is logically incorrect. The new ShowHeadings feature in JavadocTester helps to expose such problems by making it easy to (manually) verify the hierarchy of headings in a file. > > stylesheet changes ... > > The standard javadoc stylesheet uses almost-global settings for the font size and style of the 6 levels of headings. For the most part, these settings are used across all pages. (The exceptions are for the index files in the frames feature, which, as has already been noted, is going away sometime soon.) The one additional visual cue for headings is the occasional use of a grey background for headings, which does vary depending on the context (i.e. page and heading-level.) > > The only change to the stylesheet at this point is to ensure that the grey background is used in the same positions as before ... typically for the heading that precedes a list of elements, such as a list of members in a class. The global settings for the font size and style are (intentionally) not modified in this changeset. This means that the appearance of headings is generally consistent across all kinds of pages, although there are some visual changes in some of the generated pages . We could revisit that if necessary to get the same appearance as before, meaning that we would be visually inconsistent between different kinds of pages. If so, that should be a different cleanup task. I note that it would be a CSS-only task; I believe there is enough info in the HTML that no further changes to the generated HTML would be necessary. > > In various discussions regarding this feature, concerns were expressed that "<h1> is too big". Given the existing definitions within the standard stylesheet, this does not seem to be a problem in practice. > > > Review tips: > > * Start by looking at how HtmlConstants was converted into Headings and MarkerComments > * For tests, start by looking at JavadocTester > * For the mundane changes to tests, you may find it worth looking at the patch files instead of the side-by-side diffs > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8215307 > Webrev: http://cr.openjdk.java.net/~jjg/8215307/webrev.00/ > From hannes.wallnoefer at oracle.com Tue Jan 29 14:22:16 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Tue, 29 Jan 2019 15:22:16 +0100 Subject: RFR: 8215577: Remove javadoc support for HTML 4 In-Reply-To: <a62db6b0-2e7b-047e-c1d2-bbdba5693ede@oracle.com> References: <99dbda8f-d5eb-420d-86e4-1e89ace786bb@oracle.com> <66670def-6dfc-d685-699e-e4ba2519efe1@oracle.com> <EE10A023-B252-44DE-AB72-763B6D3E9B26@oracle.com> <a62db6b0-2e7b-047e-c1d2-bbdba5693ede@oracle.com> Message-ID: <BDA7F77C-FF8B-45D0-ABC8-6D49FEF42B3D@oracle.com> Looks good to me! Hannes > Am 29.01.2019 um 07:22 schrieb Priya Lakshmi Muthuswamy <priya.lakshmi.muthuswamy at oracle.com>: > > Hi Hannes, > > Thanks for the review. > I have removed the unused summary string computation from the code. > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.02/ > > Thanks, > Priya > > On 1/28/2019 8:48 PM, Hannes Walln?fer wrote: >> Hi Priya, >> >> In quite a few places where Table#setSummary used to be called, the summary string for that call is still computed or at least passed around without being used. I think this is the case for all classes implementing AbstractMemberWriter#createSummaryTable(): >> >> AnnotationTypeFieldWriterImpl >> AnnotationTypeRequiredMemberWriterImpl (method getTableSummary() is never used) >> ConstructorWriterImpl >> EnumConstantWriterImpl >> FieldWriterImpl >> MethodWriterImpl >> NestedClassWriterImpl >> PropertyWriterImpl >> >> There may be a few other passing around summary arguments that aren?t used. >> >> Otherwise your patch looks good to me. >> >> Hannes >> >> >>> Am 28.01.2019 um 10:48 schrieb Priya Lakshmi Muthuswamy <priya.lakshmi.muthuswamy at oracle.com>: >>> >>> forgot to mention CSR . >>> JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 >>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ >>> CSR : https://bugs.openjdk.java.net/browse/JDK-8215578 >>> >>> Thanks, >>> Priya >>> On 1/28/2019 10:14 AM, Priya Lakshmi Muthuswamy wrote: >>>> Hi, >>>> >>>> Kindly review the changes for the removal for html4 support from javadoc. >>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8215577 >>>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8215577/webrev.01/ >>>> >>>> Thanks, >>>> Priya >>>> From hannes.wallnoefer at oracle.com Tue Jan 29 15:45:05 2019 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Tue, 29 Jan 2019 16:45:05 +0100 Subject: Feedback on improved Javadoc search Message-ID: <005EF065-ACFC-4A21-8C8B-1C2DBCCA3322@oracle.com> Hi all, I?m looking for feedback on the Javadoc search feature which I?ve been trying to improve. A prototype is available for testing here: http://cr.openjdk.java.net/~hannesw/8178982/api.03/ A short list of things that are changed compared to the current implementation: - Match against word boundaries instead of anywhere in a name, e.g. `in` will match `invoke` but not `print` - Allow search to go all the way from package name to member name - Allow partial/camel case style matches anywhere, e.g. `j.l.Obj.e` will match `java.lang.Object.equals(Object)` - Try to provide better ranking of results and suppress peripheral matches I?m interested in feedback of any kind: how it works for you, whether or not it supports your search habits, and whether the results are what you expect them to be. Thanks, Hannes From priya.lakshmi.muthuswamy at oracle.com Wed Jan 30 12:18:36 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Wed, 30 Jan 2019 17:48:36 +0530 Subject: RFR : 8213354 : Support package-specific stylesheets Message-ID: <2f575909-d2e8-73b7-95ff-a1b3a7100446@oracle.com> Hi, Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8213354 Package specific stylesheets needs to placed under doc-files directory of a package. DocFilesHandler looks for any css file and adds them to the generated html pages. webrev : http://cr.openjdk.java.net/~pmuthuswamy/8213354/webrev.00/ Thanks, Priya From martinrb at google.com Wed Jan 30 20:46:30 2019 From: martinrb at google.com (Martin Buchholz) Date: Wed, 30 Jan 2019 12:46:30 -0800 Subject: Feedback on improved Javadoc search In-Reply-To: <005EF065-ACFC-4A21-8C8B-1C2DBCCA3322@oracle.com> References: <005EF065-ACFC-4A21-8C8B-1C2DBCCA3322@oracle.com> Message-ID: <CA+kOe0-UsFFL9KzV09iuxahBKgKxOTwjimuomaQR2KevEQ1d-g@mail.gmail.com> Maybe not quite what you want, but: - javadoc search is awesome! - I'd like a snippet of html so I can embed a doc search box in my own home page. - I'd like (browser-specific) instructions so that I can do a search from my browser's address bar. - I'd like a help button so I can easily look up the semantics of API search, especially as it acquires more convenient but hard-to-discover features. - Where is the definitive source of information on javadoc search? The JEP itself is frozen now. - If I right-mouse-click on "SEARCH" the previous word "METHOD" is also highlighted, and Chrome offers to do a Google search on "METHODSEARCH" ("""did you mean METHOD SEARCH?""" Nope.) On Tue, Jan 29, 2019 at 7:57 AM Hannes Walln?fer < hannes.wallnoefer at oracle.com> wrote: > Hi all, > > I?m looking for feedback on the Javadoc search feature which I?ve been > trying to improve. > > A prototype is available for testing here: > > http://cr.openjdk.java.net/~hannesw/8178982/api.03/ > > A short list of things that are changed compared to the current > implementation: > > - Match against word boundaries instead of anywhere in a name, e.g. `in` > will match `invoke` but not `print` > > - Allow search to go all the way from package name to member name > > - Allow partial/camel case style matches anywhere, e.g. `j.l.Obj.e` will > match `java.lang.Object.equals(Object)` > > - Try to provide better ranking of results and suppress peripheral > matches > > I?m interested in feedback of any kind: how it works for you, whether or > not it supports your search habits, and whether the results are what you > expect them to be. > > Thanks, > Hannes -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190130/d470bfbb/attachment.html> From priya.lakshmi.muthuswamy at oracle.com Thu Jan 31 08:41:21 2019 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Thu, 31 Jan 2019 14:11:21 +0530 Subject: [12] RFR : 8218134 : Modify the jQuery.md file to reflect the exact jQuery license content. Message-ID: <3efbc0f0-21ff-9b5b-8d0d-c23a197a928a@oracle.com> Hi, Kindly review the changes for updating the jQuery license content. webrev : http://cr.openjdk.java.net/~pmuthuswamy/8218134/webrev.00/ Thanks, Priya From sundararajan.athijegannathan at oracle.com Thu Jan 31 08:54:16 2019 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Thu, 31 Jan 2019 14:24:16 +0530 Subject: [12] RFR : 8218134 : Modify the jQuery.md file to reflect the exact jQuery license content. In-Reply-To: <3efbc0f0-21ff-9b5b-8d0d-c23a197a928a@oracle.com> References: <3efbc0f0-21ff-9b5b-8d0d-c23a197a928a@oracle.com> Message-ID: <5C52B7B8.8000400@oracle.com> Looks good. -Sundar On 31/01/19, 2:11 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the changes for updating the jQuery license content. > > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8218134/webrev.00/ > > Thanks, > Priya >