Re: RFR: 8332545: Fix handling of HTML5 entities in Markdown comments
On Mon, 20 May 2024 23:21:31 GMT, Erik Joelsson wrote: > Build change looks good. Thank you - PR Comment: https://git.openjdk.org/jdk/pull/19317#issuecomment-2121488205
Integrated: 8332545: Fix handling of HTML5 entities in Markdown comments
On Mon, 20 May 2024 20:17:10 GMT, Jonathan Gibbons wrote: > Please review a small fix to address a crash when handling HTML5 entities in > a Markdown doc comment. > > The path for the `entities.txt` (originally `entities.properties`) was not > correctly imported when importing the latest version of `commonmark-java`. > And, the makefiles need to be updated to include the `.txt` file in the > image. (The interim module for the interim javadoc already had this fix.) > > A simple new test is provided, containing entities that previously caused > `javadoc` to crash. This pull request has now been integrated. Changeset: 6e805127 Author:Jonathan Gibbons URL: https://git.openjdk.org/jdk/commit/6e805127f8091d46205165746d7c59a40703958d Stats: 79 lines in 3 files changed: 77 ins; 0 del; 2 mod 8332545: Fix handling of HTML5 entities in Markdown comments Reviewed-by: prappo, erikj - PR: https://git.openjdk.org/jdk/pull/19317
Re: RFR: 8332545: Fix handling of HTML5 entities in Markdown comments
On Mon, 20 May 2024 21:20:29 GMT, Pavel Rappo wrote: > Assuming the test fails without the fix, but passes with it, looks good. Confirmed the test fails without the fix (crash, as reported) and passes with the fix. - PR Comment: https://git.openjdk.org/jdk/pull/19317#issuecomment-2121306491
RFR: 8332545: Fix handling of HTML5 entities in Markdown comments
Please review a small fix to address a crash when handling HTML5 entities in a Markdown doc comment. The path for the `entities.txt` (originally `entities.properties`) was not correctly imported when importing the latest version of `commonmark-java`. And, the makefiles need to be updated to include the `.txt` file in the image. (The interim module for the interim javadoc already had this fix.) A simple new test is provided, containing entities that previously caused `javadoc` to crash. - Commit messages: - JDK-8332545: Fix handling of HTML5 entities in Markdown comments Changes: https://git.openjdk.org/jdk/pull/19317/files Webrev: https://webrevs.openjdk.org/?repo=jdk=19317=00 Issue: https://bugs.openjdk.org/browse/JDK-8332545 Stats: 79 lines in 3 files changed: 77 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/19317.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/19317/head:pull/19317 PR: https://git.openjdk.org/jdk/pull/19317
Integrated: 8298405: Implement JEP 467: Markdown Documentation Comments
On Thu, 26 Oct 2023 23:29:00 GMT, Jonathan Gibbons wrote: > Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML This pull request has now been integrated. Changeset: 0a58cffe Author:Jonathan Gibbons URL: https://git.openjdk.org/jdk/commit/0a58cffe88ba823e71fcdcca64b784ed04ca5398 Stats: 26546 lines in 250 files changed: 25839 ins; 257 del; 450 mod 8298405: Implement JEP 467: Markdown Documentation Comments 8329296: Update Elements for '///' documentation comments Co-authored-by: Jim Laskey Reviewed-by: prappo, darcy, hannesw - PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v69]
On Thu, 16 May 2024 16:44:51 GMT, Hannes Wallnöfer wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> update tests for dangling doc comments, per review feedback > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java > line 1465: > >> 1463: private final HtmlRenderer renderer = HtmlRenderer.builder() >> 1464: .nodeRendererFactory(headingRendererFactory) >> 1465: .extensions(List.of(tablesExtn/*, headingIdsExtn*/)) > > Is there a reason to keep the commented argument? no, it should go; thanks for catching - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1603864642
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v70]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/bfa35bd4..a0df7a4b Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=69 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=68-69 Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v69]
On Thu, 16 May 2024 15:05:32 GMT, Jonathan Gibbons wrote: > There were some community comments objecting the use of `///` for markdown > documentation, and called for alternative syntaxes like `/*markdown */`. This was [addressed](https://openjdk.org/jeps/467#Using-///-for-Markdown-documentation-comments) in an update to JEP 467. - PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-2115749018
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v69]
On Thu, 16 May 2024 15:03:26 GMT, Pavel Rappo wrote: > If you are concerned with it being a lint warning rather than a **doc**lint > warning, then it's a technicality: doclint sees less than lint sees, and > sadly not enough for that check. Thus, that check was put in `lint. To clarify that a bit ... There's a subtle difference between _documentation comments_ and _documentation comments as used with the standard doclet_. From the beginning, documentation comments have been those enclosed in `/**...*/` but there has never been a formal specification that the only content is that accepted by the standard doclet. Indeed, over the years, there have been various doclets, not all from Sun/Oracle, and not all accepting the content syntax used by the standard doclet. This practice continues with the introduction of `///` comments. So, there are actually two issues conflated in this work: 1. introducing the use of `///` for documentation comments 2. introducing the use of Markdown for some comments They go together because it would be silly/confusing to introduce `///` comments by themselves, and figuring out what to do with them until the use of Markdown was introduced. Arguably, the first bullet by itself could have been a Preview feature, but it probably falls below any appropriate threshold. You might also note that `Elements.getDocComment` and friends say nothing about the syntactic form of the content of any doc comment after the lexical wrappings have been removed. In particular, words like HTML and Markdown do not appear in the specs for these methods. This is intentional and means that a different doclet could interpret the content of the doc comment in any way that it chooses. Back to this thread, and `-Xlint` vs `-Xdoclint`: `doclint` is specifically about issues within the content of doc comments as defined in the `JavaDoc Documentation Comment Specification for the Standard Docket` and interpreted by the standard doclet. `dangling-doc-comments` is not specific to comments seen by the standard doclet. It applies to all doc comments, whatever the form of their content. As such, it is a `javac` lexical check, and belongs in `-Xlint`. - PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-2115724002
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v69]
On Thu, 16 May 2024 15:03:26 GMT, Pavel Rappo wrote: > My rationale for a potential preview is that we changed > `-Xlint:dangling-doc-comments` as `///` is now dangling doc comment. Is this > considered a Java programming language change? There were some community > comments objecting the use of `///` for markdown documentation, and called > for alternative syntaxes like `/*markdown */`. There is no change to the Java Language Specification in this work. In fact, JLS does not mention documentation comments in any form -- either traditional or end-of-line comments. (The original version of JLS did mention them; all subsequent versions do not.) As a result, even though `javadoc` is used to _generate_ the Java SE specifications, `javadoc`, the standard doclet, and documentation comments are all JDK features, not Java SE features. Given the relative size of this feature, compared to other new `javadoc` work, I think it is fair to say that if there had been a way to _preview_ the work, we would have considered doing so. But "preview" and JEP 12 are specifically for Java SE: >A preview feature is a new feature of the Java language, Java Virtual Machine, >or Java SE API that is fully specified, fully implemented, and yet >impermanent. It is available in a JDK feature release to provoke developer >feedback based on real world use; this may lead to it becoming permanent in a >future Java SE Platform. - PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-2115502498
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v67]
On Wed, 15 May 2024 10:08:19 GMT, Pavel Rappo wrote: > I think we should add a test to verify that if `--disable-line-doc-comments` > is specified, no `///` dangling comments are reported. Added more tests for dangling doc comments. Note we cannot currently use `-Xlint:dangling-doc-comments` in javadoc itself, so the new tests are part of the javac set of tests. - PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-2113453038
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v69]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: update tests for dangling doc comments, per review feedback - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/43546101..bfa35bd4 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=68 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=67-68 Stats: 110 lines in 9 files changed: 95 ins; 0 del; 15 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v68]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 93 commits: - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit. - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Remove `--no-fonts` from `MISSING_IN_MAN_PAGE` - Update javadoc.1 troff man page - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - address review feedback, to improve testing of changes to Elements - update copyright years - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - update commonmark-java from 0.21.0 to 0.22.0 - ... and 83 more: https://git.openjdk.org/jdk/compare/61aff6db...43546101 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=67 Stats: 26438 lines in 242 files changed: 25744 ins; 257 del; 437 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v67]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 91 commits: - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Remove `--no-fonts` from `MISSING_IN_MAN_PAGE` - Update javadoc.1 troff man page - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - address review feedback, to improve testing of changes to Elements - update copyright years - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - update commonmark-java from 0.21.0 to 0.22.0 - Remove links to `jdk.javadoc` module from `java.compiler` module` - Suppress warnings building tests - ... and 81 more: https://git.openjdk.org/jdk/compare/524aaad9...cc12140a - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=66 Stats: 26446 lines in 243 files changed: 25749 ins; 257 del; 440 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v66]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Remove `--no-fonts` from `MISSING_IN_MAN_PAGE` - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/9ad5c398..e48ebb53 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=65 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=64-65 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v65]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Update javadoc.1 troff man page - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/e42632a9..9ad5c398 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=64 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=63-64 Stats: 23 lines in 1 file changed: 10 ins; 3 del; 10 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v56]
On Fri, 12 Apr 2024 17:39:11 GMT, Joe Darcy wrote: > There should be some quick testing of the new default method on Elements > using the VacuousElements implementation; see > `test/langtools/tools/javac/processing/model/util/elements` for some examples. @jddarcy I've reorganized the tests in this area a bit, and moved the testing for `DocCommentKind` to a new test, which includes testing the default method, using `VacuousElements` (nice trick, that, by the way.). Although now renamed, the older `TestGetDocComments` is now closer to the original form, with the testing for `getDocCommentKind` being moved to a new test class. - PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-2089096959
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v64]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 88 commits: - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - address review feedback, to improve testing of changes to Elements - update copyright years - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - update commonmark-java from 0.21.0 to 0.22.0 - Remove links to `jdk.javadoc` module from `java.compiler` module` - Suppress warnings building tests - Merge with upstream/master - address review feedback for updates to Elements and friends - address review feedback for updates to Elements and friends - ... and 78 more: https://git.openjdk.org/jdk/compare/0a24daec...e42632a9 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=63 Stats: 26434 lines in 242 files changed: 25748 ins; 263 del; 423 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v63]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback, to improve testing of changes to Elements - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/6576d024..fe94ab8e Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=62 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=61-62 Stats: 111 lines in 3 files changed: 87 ins; 14 del; 10 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v62]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: update copyright years - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/20a384b6..6576d024 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=61 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=60-61 Stats: 68 lines in 62 files changed: 0 ins; 7 del; 61 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v61]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 85 commits: - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - update commonmark-java from 0.21.0 to 0.22.0 - Remove links to `jdk.javadoc` module from `java.compiler` module` - Suppress warnings building tests - Merge with upstream/master - address review feedback for updates to Elements and friends - address review feedback for updates to Elements and friends - add support for JDK-8329296: Update Elements for '///' documentation comments - add support for `--disable-line-doc-comments` - Merge branch '8298405.doclet-markdown-v3' of https://github.com/jonathan-gibbons/jdk into 8298405.doclet-markdown-v3 - ... and 75 more: https://git.openjdk.org/jdk/compare/b96b38c2...20a384b6 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=60 Stats: 26326 lines in 243 files changed: 25679 ins; 260 del; 387 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v60]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: update commonmark-java from 0.21.0 to 0.22.0 - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/fadc130b..74c86f51 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=59 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=58-59 Stats: 2382 lines in 53 files changed: 2020 ins; 258 del; 104 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v59]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Remove links to `jdk.javadoc` module from `java.compiler` module` - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/a884ae36..fadc130b Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=58 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=57-58 Stats: 9 lines in 1 file changed: 0 ins; 5 del; 4 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v58]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Suppress warnings building tests - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/c4709cf5..a884ae36 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=57 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=56-57 Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v57]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 81 commits: - Merge with upstream/master - address review feedback for updates to Elements and friends - address review feedback for updates to Elements and friends - add support for JDK-8329296: Update Elements for '///' documentation comments - add support for `--disable-line-doc-comments` - Merge branch '8298405.doclet-markdown-v3' of https://github.com/jonathan-gibbons/jdk into 8298405.doclet-markdown-v3 - Merge pull request #3 from lahodaj/fix-positions-replacement Fixing positions when transforming javadoc text with replacement characters. - Merge branch '8298405.doclet-markdown-v3' into fix-positions-replacement - Fixing positions when transforming javadoc text with replacement characters. - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - ... and 71 more: https://git.openjdk.org/jdk/compare/a920af23...c4709cf5 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=56 Stats: 24098 lines in 228 files changed: 23453 ins; 260 del; 385 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Integrated: 8303689: javac -Xlint could/should report on "dangling" doc comments
On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons wrote:
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
This pull request has now been integrated.
Changeset: a920af23
Author:Jonathan Gibbons
URL:
https://git.openjdk.org/jdk/commit/a920af233a11592af113f456f7608cb59dd1617e
Stats: 482 lines in 58 files changed: 385 ins; 3 del; 94 mod
8303689: javac -Xlint could/should report on "dangling" doc comments
Reviewed-by: vromero, ihse, prr
-
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v10]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
fix typo
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/39689a52..48e8b0a2
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk=18527=09
- incr: https://webrevs.openjdk.org/?repo=jdk=18527=08-09
Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v9]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
revert need to disable warning
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/16a265a2..39689a52
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk=18527=08
- incr: https://webrevs.openjdk.org/?repo=jdk=18527=07-08
Stats: 3 lines in 1 file changed: 0 ins; 2 del; 1 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v8]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request with a new target base due to a
merge or a rebase. The pull request now contains 11 commits:
- Merge remote-tracking branch 'upstream/master' into
8303689.dangling-comments # Please enter a commit message to explain why this
merge is necessary, # especially if it merges an updated upstream into a topic
branch. # # Lines starting with '#' will be ignored, and an empty message
aborts # the
commit.
- Merge with upstream/master
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge with upstream/master
- update test
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- ... and 1 more: https://git.openjdk.org/jdk/compare/1c238d43...16a265a2
-
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk=18527=07
Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v7]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request with a new target base due to a
merge or a rebase. The pull request now contains 10 commits:
- Merge with upstream/master
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge with upstream/master
- update test
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
-
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk=18527=06
Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v6]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request with a new target base due to a
merge or a rebase. The pull request now contains seven commits:
- Merge with upstream/master
- update test
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
-
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk=18527=05
Stats: 488 lines in 61 files changed: 389 ins; 3 del; 96 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v5]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
update test
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/f3670e7a..8ad8b818
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk=18527=04
- incr: https://webrevs.openjdk.org/?repo=jdk=18527=03-04
Stats: 6 lines in 1 file changed: 6 ins; 0 del; 0 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v4]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request with a new target base due to a
merge or a rebase. The incremental webrev excludes the unrelated changes
brought in by the merge/rebase. The pull request contains five additional
commits since the last revision:
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/3f745431..f3670e7a
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk=18527=03
- incr: https://webrevs.openjdk.org/?repo=jdk=18527=02-03
Stats: 42074 lines in 1058 files changed: 18282 ins; 15937 del; 7855 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v3]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
call `saveDanglingDocComments` for local variable declarations
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/56d6dcac..3f745431
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk=18527=02
- incr: https://webrevs.openjdk.org/?repo=jdk=18527=01-02
Stats: 10 lines in 1 file changed: 5 ins; 2 del; 3 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v2]
On Wed, 3 Apr 2024 10:01:37 GMT, Magnus Ihse Bursie wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> adjust call for `saveDanglingDocComments` for enum members > > The build changes look okay. > > Do you have any plan of going through all the Java modules and fixing the > issues, or opening JBS issues to have them fixed? Or will these lint warnings > remain disabled for the foreseeable future? @magicus > The build changes look okay. > > Do you have any plan of going through all the Java modules and fixing the > issues, or opening JBS issues to have them fixed? Or will these lint warnings > remain disabled for the foreseeable future? The plan is to create an umbrella bug to clean up the individual modules. There is interest to clean up `java.base`, to keep that one free of any warnings, and I can see that the lang tools modules will get cleaner up as well. It will be up to other component teams to decide if and when to clean up other parts of the system. Once this work has been integrated, it is relatively easy to enable the warnings for a module and to fix the ensuing issues. Since any changes "only" involve comments, it should be reasonably easy to fix them, unlike some pervasive other warnings, like `this-escape`. - PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2052174696
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v2]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
adjust call for `saveDanglingDocComments` for enum members
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/3d6f1f95..56d6dcac
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk=18527=01
- incr: https://webrevs.openjdk.org/?repo=jdk=18527=00-01
Stats: 5 lines in 1 file changed: 3 ins; 2 del; 0 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v56]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback for updates to Elements and friends - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/21f5b004..d4c2c73b Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=55 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=54-55 Stats: 9 lines in 2 files changed: 0 ins; 0 del; 9 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v55]
On Tue, 9 Apr 2024 08:53:10 GMT, Pavel Rappo wrote:
>> Jonathan Gibbons has updated the pull request incrementally with one
>> additional commit since the last revision:
>>
>> add support for JDK-8329296: Update Elements for '///' documentation
>> comments
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/model/JavacElements.java
> line 443:
>
>> 441: @DefinedBy(Api.LANGUAGE_MODEL)
>> 442: public CommentKind getDocCommentKind(Element e) {
>> 443: return getDocCommentItem(e, ((docCommentTable, tree) ->
>> docCommentTable.getCommentKind(tree)));
>
> Nit:
> Suggestion:
>
> return getDocCommentItem(e, ((docCommentTable, tree) ->
> docCommentTable.getCommentKind(tree)));
Fixed
> src/jdk.compiler/share/classes/com/sun/tools/javac/model/JavacElements.java
> line 443:
>
>> 441: @DefinedBy(Api.LANGUAGE_MODEL)
>> 442: public CommentKind getDocCommentKind(Element e) {
>> 443: return getDocCommentItem(e, ((docCommentTable, tree) ->
>> docCommentTable.getCommentKind(tree)));
>
> Again:
> Suggestion:
>
> return getDocCommentItem(e, ((docCommentTable, tree) ->
> docCommentTable.getCommentKind(tree)));
Fixed.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1561382358
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1561382835
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v55]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: add support for JDK-8329296: Update Elements for '///' documentation comments - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/37646287..21f5b004 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=54 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=53-54 Stats: 331 lines in 10 files changed: 291 ins; 20 del; 20 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v43]
On Thu, 29 Feb 2024 11:39:41 GMT, Hannes Wallnöfer wrote: >> Setext headings only come in "level 1" and "level 2" flavors. >> And, at the time the renderer sees the AST, the difference between ATX and >> setext headings is erased. They're just "headings". >> >> I also think it is better to have a simple rule than an "adaptive" rule. If >> you start doing a more complex rule, you have to consider the effect on >> subheadings as well. > > I suspected it was about the limited range of Setext headings. Yesterday my > proposal was intentionally vague, but thinking about this again I think we > should actually do the simplest and least intrusive thing possible: > > // minLevel is 4 for members, 2 for page-level elements, 1 for doc files > "h" + Math.max(heading.getLevel(), minLevel); > > This arguably generates the correct heading for most simple use cases. What > it doesn't do is to translate whole hierarchies of headings, but I would > argue that few people people need this and those who do should figure out the > rules and use the correct ATX headings. Generally, I disagree with the policy here. In particular, this suggestion "squashes"/"merges" heading levels at the more significant end of the range (i.e. h1, h2) and not at the least significant end of the range (i.e. h5, h6). And, while we do specify the required heading levels in "traditional" doc comments, that seems less than optimal. (I note in times past we had to _modify_ the headings in doc comments as a result of the policy). Given all that, it seems better/simpler to specify that an author should start the headings in any comment at level 1 and have the tool adjust the level as needed. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1543389787
Re: RFR: JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
On Wed, 27 Mar 2024 22:41:33 GMT, Pavel Rappo wrote: > Would this be the first lint -- not doclint -- warning related to comments, > let alone doc comments? No. `-Xlint:dep-ann` correlates `@Deprecated` annotations with `@deprecated` tags in doc comments. > src/jdk.javadoc/share/man/javadoc.1 line 111: > >> 109: source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more >> 110: specifically, \f[V]-Xlint:dangling-doc-comments\f[R]. >> 111: Within a source file, you may use suppress any warnings generated by > > Typo? > Suggestion: > > Within a source file, you may suppress any warnings generated by Thanks; I'll check the underlying original. - PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024162355 PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1542157047
RFR: JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
Please review the updates to support a proposed new
`-Xlint:dangling-doc-comments` option.
The work can be thought of as in 3 parts:
1. An update to the `javac` internal class `DeferredLintHandler` so that it is
possible to specify the appropriately configured `Lint` object when it is time
to consider whether to generate the diagnostic or not.
2. Updates to the `javac` front end to record "dangling docs comments" found
near the beginning of a declaration, and to report them using an instance of
`DeferredLintHandler`. This allows the warnings to be enabled or disabled using
the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The procedure
for handling dangling doc comments is described in this comment in
`JavacParser`.
* Dangling documentation comments are handled as follows.
* 1. {@code Scanner} adds all doc comments to a queue of
* recent doc comments. The queue is flushed whenever
* it is known that the recent doc comments should be
* ignored and should not cause any warnings.
* 2. The primary documentation comment is the one obtained
* from the first token of any declaration.
* (using {@code token.getDocComment()}.
* 3. At the end of the "signature" of the declaration
* (that is, before any initialization or body for the
* declaration) any other "recent" comments are saved
* in a map using the primary comment as a key,
* using this method, {@code saveDanglingComments}.
* 4. When the tree node for the declaration is finally
* available, and the primary comment, if any,
* is "attached", (in {@link #attach}) any related
* dangling comments are also attached to the tree node
* by registering them using the {@link #deferredLintHandler}.
* 5. (Later) Warnings may be genereated for the dangling
* comments, subject to the {@code -Xlint} and
* {@code @SuppressWarnings}.
3. Updates to the make files to disable the warnings in modules for which the
warning is generated. This is often because of the confusing use of `/**` to
create box or other standout comments.
-
Commit messages:
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk=18527=00
Issue: https://bugs.openjdk.org/browse/JDK-8303689
Stats: 477 lines in 60 files changed: 368 ins; 5 del; 104 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v54]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: add support for `--disable-line-doc-comments` - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/a8ea1c72..37646287 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=53 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=52-53 Stats: 134 lines in 9 files changed: 132 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8324774: Add DejaVu web fonts [v2]
On Wed, 20 Mar 2024 15:54:12 GMT, Hannes Wallnöfer wrote: >> This change adds the DejaVu web fonts that were previously maintained >> externally to the open repository so they are available both in JDK API >> documentation and any API documentation generated with the `javadoc` tool. >> All files added in this PR are the same as the ones previously maintained >> externally, with the exception of added license and name/version comments in >> `dejavu.css`. >> >> Copying of font files to the generated documentation is done by looking for >> font file names in `dejavu.css`, so font file names can be changed without >> changing the code. However, the font file list is hard-coded in >> `APITest.java`. `CheckLibraryVersions.java` is updated to make sure the name >> and version in the legal file matches the one in the stylesheet. Of course I >> also performed manual tests to make sure the font and legal files are copied >> to the output tree and used correctly in browsers. >> >> Once #17411 is integrated, `dejavu.css` should also be added to the list of >> files checked by the new "pass-through" test. > > Hannes Wallnöfer has updated the pull request incrementally with two > additional commits since the last revision: > > - JDK-8327385: Add JavaDoc option to exclude web fonts from generated > documentation > - Merge try-with-resource statements Marked as reviewed by jjg (Reviewer). I like the new stuff for `JavadocTester` wrapped up in this work. - PR Review: https://git.openjdk.org/jdk/pull/17633#pullrequestreview-1962024918 PR Comment: https://git.openjdk.org/jdk/pull/17633#issuecomment-2021719299
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v53]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 76 commits: - Merge branch '8298405.doclet-markdown-v3' of https://github.com/jonathan-gibbons/jdk into 8298405.doclet-markdown-v3 - Merge pull request #3 from lahodaj/fix-positions-replacement Fixing positions when transforming javadoc text with replacement characters. - Merge branch '8298405.doclet-markdown-v3' into fix-positions-replacement - Fixing positions when transforming javadoc text with replacement characters. - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - update man page - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Merge with upstream/master - Merge with upstream/master - improve first-sentence break in Markdown comments - ... and 66 more: https://git.openjdk.org/jdk/compare/3f2e849c...a8ea1c72 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=52 Stats: 23635 lines in 209 files changed: 23012 ins; 254 del; 369 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v52]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with three additional commits since the last revision: - Merge pull request #3 from lahodaj/fix-positions-replacement Fixing positions when transforming javadoc text with replacement characters. - Merge branch '8298405.doclet-markdown-v3' into fix-positions-replacement - Fixing positions when transforming javadoc text with replacement characters. - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/03652d2f..477fb155 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=51 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=50-51 Stats: 38 lines in 2 files changed: 26 ins; 0 del; 12 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v51]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 71 commits: - update man page - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Merge with upstream/master - Merge with upstream/master - improve first-sentence break in Markdown comments - add test cases for links to anchors - fix `textOf` method to accommodate Markdown content. - avoid relying on unspecified behavior `List.toString` - fix test after merge - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - ... and 61 more: https://git.openjdk.org/jdk/compare/c901da48...03652d2f - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=50 Stats: 23609 lines in 209 files changed: 22986 ins; 254 del; 369 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v50]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 69 commits: - Merge with upstream/master - Merge with upstream/master - improve first-sentence break in Markdown comments - add test cases for links to anchors - fix `textOf` method to accommodate Markdown content. - avoid relying on unspecified behavior `List.toString` - fix test after merge - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Revise `Markdown.update` to better handle container blocks. - Refactor most of TestMarkdown.java into separate tests, grouped by functionality - ... and 59 more: https://git.openjdk.org/jdk/compare/65a84c26...635af77d - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=49 Stats: 23526 lines in 208 files changed: 22955 ins; 228 del; 343 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v49]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 68 commits: - Merge with upstream/master - improve first-sentence break in Markdown comments - add test cases for links to anchors - fix `textOf` method to accommodate Markdown content. - avoid relying on unspecified behavior `List.toString` - fix test after merge - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Revise `Markdown.update` to better handle container blocks. - Refactor most of TestMarkdown.java into separate tests, grouped by functionality - add support for (top-level) trailing code blocks add simple test case with tabs add TestMarkdownCodeBlocks.testTypical - ... and 58 more: https://git.openjdk.org/jdk/compare/586396cb...76eccbf4 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=48 Stats: 23757 lines in 208 files changed: 23030 ins; 281 del; 446 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v48]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: improve first-sentence break in Markdown comments - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/8dfd9e08..81279a74 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=47 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=46-47 Stats: 50 lines in 2 files changed: 45 ins; 0 del; 5 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v47]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: add test cases for links to anchors - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/fc76e8c7..8dfd9e08 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=46 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=45-46 Stats: 60 lines in 1 file changed: 60 ins; 0 del; 0 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v46]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision: - fix `textOf` method to accommodate Markdown content. - avoid relying on unspecified behavior `List.toString` - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/292ff0f1..fc76e8c7 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=45 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=44-45 Stats: 43 lines in 3 files changed: 34 ins; 0 del; 9 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v44]
On Mon, 4 Mar 2024 15:16:32 GMT, Pavel Rappo wrote:
> > I have a test case to report. The following results in no `@param`
> > information being rendered, which I think is a bug:
> > ```
> > /// Hello, _Markdown_ world!
> > ///
> > ///
> > /// @param hello
> > ///
> > ///
> > public class C { }
> > ```
>
> Scratch that. After experimenting a bit more with **traditional** javadoc
> comments, I realised that it might be expected that `@param` would be lost in
> that `...` block; okay.
>
> Still, I find it surprising that the description of the `@param` tag in the
> above comment, hosted in `///` or `/**...*/`, is a single node of type
> `RawText` with the following content:
>
> ```
> hello
>
> ```
>
> (Note, the content includes ``.)
The Markdown aspect of this is behaving about as well as can be expected. But
the generated form is certainly confusing and can be considered a
less-than-optimal presentation of a paragraph within a definition list. You
can see the same behavior in a traditional comment with `@param
hello`. Ideally, we could/should tweak the CSS for this situation, in a
separate changeset.
-
PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1979452615
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v45]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 63 commits: - fix test after merge - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Revise `Markdown.update` to better handle container blocks. - Refactor most of TestMarkdown.java into separate tests, grouped by functionality - add support for (top-level) trailing code blocks add simple test case with tabs add TestMarkdownCodeBlocks.testTypical - fix whitespace - fix Markdown.update for new POST_LIST_INDENT test case given in review feedback - refactor tests for Markdown headings into a separate test class. - update DocCommentParser and tests to improve handling of code blocks and code spans in Markdown documentation comments - fix indentation, for consistency - ... and 53 more: https://git.openjdk.org/jdk/compare/6f8d351e...292ff0f1 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=44 Stats: 23548 lines in 205 files changed: 22863 ins; 252 del; 433 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v44]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Revise `Markdown.update` to better handle container blocks. - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/398f93fc..0b4d9b3c Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=43 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=42-43 Stats: 348 lines in 3 files changed: 226 ins; 43 del; 79 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
On Wed, 28 Feb 2024 15:54:38 GMT, Hannes Wallnöfer wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> Refactor most of TestMarkdown.java into separate tests, grouped by >> functionality > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java > line 1601: > >> 1599: : eKind != ElementKind.OTHER ? 1 // module, >> package, class, interface >> 1600: : 0; // doc file >> 1601: return "h" + Math.min(heading.getLevel() + offset, 6); > > I really like that we adapt the heading level to the current context, but I > notice that the code kind of expects `h1` headings to be used everywhere, and > "punishes" use of contextually correct headings by generating smaller > headings. Maybe it would be more educational to only adjust the level if it > needs adjusting? Setext headings only come in "level 1" and "level 2" flavors. And, at the time the renderer sees the AST, the difference between ATX and setext headings is erased. They're just "headings". - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1506307115
Re: Build the jdk with new or modified sources
Lorris, You cannot use new API in java.base in the code for javac, meaning the java.compiler and jdk.compiler modules. This is an ingherent limitation of the bootstrap process. -- Jon On 2/27/24 1:57 AM, Lorris wrote: Yes indeed, I am trying to use those changes from the jdk.compiler module. How can I make this work without causing problem when building the interim module ? Lorris On 26 Feb 2024, at 14:59, erik.joels...@oracle.com wrote: Hello Lorris, This is not expected behavior. Building incrementally is expected to work correctly. If you are making changes to java.base and then trying to use those changes from any of java.compiler, jdk.compiler and jdk.javadoc, you will have problems as those three modules have to be compatible with the previous JDK version (21 in this case). We build those modules for the "interim langtools" which is then used to compile the rest of the JDK by running this interim javac compiler on the boot jdk. I think the problems you are seeing appear when building the interim versions of these modules as they will never see the updates you are making to java.base. If that isn't the issue, could you share more details on what kind of environment you are building on (OS, arch etc), how you configured the build and the make command line you are using? /Erik On 2/26/24 05:40, Lorris wrote: Hello, I’m trying to build the JDK (version 23, my fork is up to date as of 2024/02/26) while adding new source files and also adding some fields or methods in existing files (in java.base and java.compiler modules). My problem is that when I try to build the image, most of the time (it seems to depend on the date of the last edited file) the new files and members I have added aren’t visible to the compiler which results in an error. Until now I have been using a workaround by building two times, firstly, only with the new code declarations and, secondly, with the references to this code. However, I’m now seeing the limits of this method. Regards, Lorris Creantor
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Refactor most of TestMarkdown.java into separate tests, grouped by functionality - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/d460ee33..398f93fc Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=42 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=41-42 Stats: 2001 lines in 9 files changed: 1143 ins; 857 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v42]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: add support for (top-level) trailing code blocks add simple test case with tabs add TestMarkdownCodeBlocks.testTypical - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/40616865..d460ee33 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=41 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=40-41 Stats: 143 lines in 3 files changed: 135 ins; 2 del; 6 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v41]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: fix whitespace - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/27bc0b9d..40616865 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=40 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=39-40 Stats: 3 lines in 1 file changed: 0 ins; 0 del; 3 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
On Thu, 22 Feb 2024 19:17:09 GMT, Jonathan Gibbons wrote: >>>I think in this place we also need to check for indented code blocks, since >>>we reduced currIndent and may have 4 or more character indentation compared >>>to the new currIndent value. >> >> This seems wrong. Surely, we should not reduce the indentation and then for >> the same line in the comment check for an extra-indented line. Or else I am >> missing something. >> >> That being said, thanks for the test case. I will investigate it. > > Update: I see and understand your test case. Update: I found that more elegant solution you hinted at, by refactoring the method from nested `if` statements to a series of checks with early returns. The test case you provided now works as expected. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499918026
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v40]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: fix Markdown.update for new POST_LIST_INDENT test case given in review feedback - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/72420419..27bc0b9d Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=39 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=38-39 Stats: 94 lines in 4 files changed: 53 ins; 16 del; 25 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
On Thu, 22 Feb 2024 19:13:57 GMT, Jonathan Gibbons wrote: >> Thanks. I will investigate your hint to look for a more elegant solution. >> Thanks for the new test case. > >>I think in this place we also need to check for indented code blocks, since >>we reduced currIndent and may have 4 or more character indentation compared >>to the new currIndent value. > > This seems wrong. Surely, we should not reduce the indentation and then for > the same line in the comment check for an extra-indented line. Or else I am > missing something. > > That being said, thanks for the test case. I will investigate it. Update: I see and understand your test case. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499787391
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
On Thu, 22 Feb 2024 15:14:32 GMT, Jonathan Gibbons wrote:
>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
>> line 1373:
>>
>>> 1371: while (indent < currIndent) {
>>> 1372: currIndent = indentStack.pop();
>>> 1373: }
>>
>> This new Markdown class looks very good!
>>
>> I think in this place we also need to check for indented code blocks, since
>> we reduced `currIndent` and may have 4 or more character indentation
>> compared to the new `currIndent` value.
>>
>> My tentative fix is to add the following code here, but maybe a more elegant
>> solution can be found by restructuring the method to first check for `indent
>> < currIndent` and then only having to check for new indented code blocks
>> once.
>>
>>
>> if (indent >= currIndent + 4 && !isParagraph(prevLineKind)) {
>> blockId++;
>> lineKind = LineKind.INDENTED_CODE_BLOCK;
>> return;
>> }
>>
>>
>> The following could be added to `TestMarkdownCodeBlocks.java` to test this
>> case:
>>
>>
>> POST_LIST_INDENT(
>> """
>> 1. list item
>>
>> second paragraph
>>
>> {@code CODE}
>> @Anno
>>
>> end""",
>> """
>>
>>
>> list item
>> second paragraph
>>
>>
>> {@code CODE}
>> @Anno
>>
>> end"""),
>
> Thanks. I will investigate your hint to look for a more elegant solution.
> Thanks for the new test case.
>I think in this place we also need to check for indented code blocks, since we
>reduced currIndent and may have 4 or more character indentation compared to
>the new currIndent value.
This seems wrong. Surely, we should not reduce the indentation and then for the
same line in the comment check for an extra-indented line. Or else I am missing
something.
That being said, thanks for the test case. I will investigate it.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499779864
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v39]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: refactor tests for Markdown headings into a separate test class. - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/5fc9c84a..72420419 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=38 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=37-38 Stats: 630 lines in 2 files changed: 345 ins; 285 del; 0 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
On Thu, 22 Feb 2024 14:53:11 GMT, Hannes Wallnöfer wrote:
>> Jonathan Gibbons has updated the pull request incrementally with two
>> additional commits since the last revision:
>>
>> - update DocCommentParser and tests to improve handling of code blocks and
>> code spans in Markdown documentation comments
>> - fix indentation, for consistency
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
> line 1373:
>
>> 1371: while (indent < currIndent) {
>> 1372: currIndent = indentStack.pop();
>> 1373: }
>
> This new Markdown class looks very good!
>
> I think in this place we also need to check for indented code blocks, since
> we reduced `currIndent` and may have 4 or more character indentation compared
> to the new `currIndent` value.
>
> My tentative fix is to add the following code here, but maybe a more elegant
> solution can be found by restructuring the method to first check for `indent
> < currIndent` and then only having to check for new indented code blocks once.
>
>
> if (indent >= currIndent + 4 && !isParagraph(prevLineKind)) {
> blockId++;
> lineKind = LineKind.INDENTED_CODE_BLOCK;
> return;
> }
>
>
> The following could be added to `TestMarkdownCodeBlocks.java` to test this
> case:
>
>
> POST_LIST_INDENT(
> """
> 1. list item
>
> second paragraph
>
> {@code CODE}
> @Anno
>
> end""",
> """
>
>
> list item
> second paragraph
>
>
> {@code CODE}
> @Anno
>
> end"""),
Thanks. I will investigate your hint to look for a more elegant solution.
Thanks for the new test case.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499408829
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision: - update DocCommentParser and tests to improve handling of code blocks and code spans in Markdown documentation comments - fix indentation, for consistency - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/25921fd0..5fc9c84a Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=37 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=36-37 Stats: 1240 lines in 4 files changed: 918 ins; 275 del; 47 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8324774: Add DejaVu web fonts
On Tue, 30 Jan 2024 16:13:42 GMT, Hannes Wallnöfer wrote:
> This change adds the DejaVu web fonts that were previously maintained
> externally to the open repository so they are available both in JDK API
> documentation and any API documentation generated with the `javadoc` tool.
> All files added in this PR are the same as the ones previously maintained
> externally, with the exception of added license and name/version comments in
> `dejavu.css`.
>
> Copying of font files to the generated documentation is done by looking for
> font file names in `dejavu.css`, so font file names can be changed without
> changing the code. However, the font file list is hard-coded in
> `APITest.java`. `CheckLibraryVersions.java` is updated to make sure the name
> and version in the legal file matches the one in the stylesheet. Of course I
> also performed manual tests to make sure the font and legal files are copied
> to the output tree and used correctly in browsers.
>
> Once #17411 is integrated, `dejavu.css` should also be added to the list of
> files checked by the new "pass-through" test.
Some suggestions.
I think there should be an option to opt-out of using these fonts.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
line 470:
> 468: // Extract font file names from CSS file
> 469: URL cssURL =
> HtmlConfiguration.class.getResource(DocPaths.RESOURCES.resolve(cssPath).getPath());
> 470: InputStream in = cssURL.openStream();
Put this in try-with-resources
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
line 476:
> 474: try (BufferedReader reader = new BufferedReader(new
> InputStreamReader(in))) {
> 475: String line;
> 476: while ((line = reader.readLine()) != null) {
Consider using `BufferedReader.lines`
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/io/BufferedReader.html#lines()
-
PR Review: https://git.openjdk.org/jdk/pull/17633#pullrequestreview-1891318432
PR Review Comment: https://git.openjdk.org/jdk/pull/17633#discussion_r1496355484
PR Review Comment: https://git.openjdk.org/jdk/pull/17633#discussion_r1496357502
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v36]
On Fri, 16 Feb 2024 07:42:47 GMT, Hannes Wallnöfer wrote: >> Jonathan Gibbons has updated the pull request incrementally with two >> additional commits since the last revision: >> >> - Support for Table Of Contents in Markdown headings >> - fix typo > > src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java > line 286: > >> 284: lineKind = (ch == '\n' || ch == '\r') ? >> LineKind.BLANK >> 285: : (indent <= 3) ? peekLineKind() >> 286: : lineKind != LineKind.OTHER ? >> LineKind.INDENTED_CODE_BLOCK > > Doesn't this cause false positives for indented code blocks? In my > understanding, indented lines [in a list > context](https://spec.commonmark.org/0.30/#example-258) and [directly > following a > blockquote](https://spec.commonmark.org/dingus/?text=%3E%20%20%20%20foo%0A%20%20%20%20%20bar%0A) > are not interpreted as code blocks (always in the case of blockquote, and > depending on the offset of text after the list marker in list items). > > Note: edited because my initial suggestion was incorrect. @hns @pavelrappo noted; working on it ... - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1494909524
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v37]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: remove obsolete comment - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/53afd804..25921fd0 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=36 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=35-36 Stats: 2 lines in 1 file changed: 0 ins; 2 del; 0 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v36]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision: - Support for Table Of Contents in Markdown headings - fix typo - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/da8752c8..53afd804 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=35 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=34-35 Stats: 102 lines in 2 files changed: 99 ins; 1 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v35]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with three additional commits since the last revision: - fix handling of `@' in a Markdown comment - improve comments for some LineKind members - update LineKind members and test - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/393d3a9c..da8752c8 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=34 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=33-34 Stats: 55 lines in 3 files changed: 49 ins; 0 del; 6 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
On Thu, 15 Feb 2024 19:36:36 GMT, Jonathan Gibbons wrote:
>> 1. Since forever, and still true, the way to specify a doclet is by its
>> name, and the tool will create the instance for you. This goes back to the
>> original old days before any API, when the only entry point was the command
>> line.
>> This implies that (a) the doclet has a no-args constructor and (b) that all
>> doclet config is done through command line options. A better solution would
>> be to add new functionality to the various javadoc tool API (some or all of
>> `Main`/`Start`/`DocumentationTool`) so that a client can initialize an
>> instance of a doclet and pass that instance into the API.
>>
>> 2. If I understand the question correctly, the code is invoked by using the
>> command-line option `-XDaccessInternalAPI` which is a preexisting hidden
>> feature already supported by `javac`. It is used in `TestTransformer.java`
>> on line 161.
>>
>> javadoc("-d", base.resolve("api").toString(),
>> "-Xdoclint:none",
>> "-XDaccessInternalAPI", // required to access JavacTrees
>> "-doclet", "TestTransformer$MyDoclet",
>> "-docletpath", System.getProperty("test.classes"),
>> "-sourcepath", src.toString(),
>> "p");
>
> I confirm that `TestTransformer.java` fails as expected with an
> `IllegalAccessError` if the option is not used.
>
> java.lang.IllegalAccessError: class TestTransformer$MyDoclet (in unnamed
> module @0x355de863) cannot access class com.sun.tools.javac.api.JavacTrees
> (in module jdk.compiler) because module jdk.compiler does not export
> com.sun.tools.javac.api to unnamed module @0x355de863
> at TestTransformer$MyDoclet.run(TestTransformer.java:139)
> at
> jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:589)
Generally, the error occurs because the `MyDoclet` class is run in a different
class loader than that used for the test. The class loader for the test
already has the necessary access permissions given, from the lines in
`@modules` in the `jtreg` test description. Ideally, we could call `new
MyDoclet()` in the main test code, and pas the instance in to the `javadoc`
call and from there to the javadoc `Start` method.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491547571
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
On Thu, 15 Feb 2024 19:39:07 GMT, Pavel Rappo wrote:
>> whitespace is handled separately, on line 280 (`readIndent`) and285 (`:
>> (indent <= 3) ? peekLineKind()`)
>
> Correct, but I believe the ordered list marker should be like this:
>
> ORDERED_LIST_ITEM(Pattern.compile("[0-9]{1,9}[.)] .*"))
> ^
>
> Note extra whitespace character. I think we should really add this to our
> tests, since lists are foundational Markdown structures, probably right after
> italics and bold.
My recollection is that the space is required. I will double check.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491552312
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
On Thu, 15 Feb 2024 19:15:25 GMT, Jonathan Gibbons wrote:
>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 571:
>>
>>> 569: // of a doclet to be specified instead of the name of the
>>> 570: // doclet class and optional doclet path.
>>> 571: // See https://bugs.openjdk.org/browse/JDK-8263219
>>
>> It's hard to understand this:
>>
>>> to permit an instance of an appropriately configured instance of a doclet
>>
>> Also: how is that piece of code used? When I commented it out, no
>> test/langtools:langtools_javadoc tests failed.
>
> 1. Since forever, and still true, the way to specify a doclet is by its
> name, and the tool will create the instance for you. This goes back to the
> original old days before any API, when the only entry point was the command
> line.
> This implies that (a) the doclet has a no-args constructor and (b) that all
> doclet config is done through command line options. A better solution would
> be to add new functionality to the various javadoc tool API (some or all of
> `Main`/`Start`/`DocumentationTool`) so that a client can initialize an
> instance of a doclet and pass that instance into the API.
>
> 2. If I understand the question correctly, the code is invoked by using the
> command-line option `-XDaccessInternalAPI` which is a preexisting hidden
> feature already supported by `javac`. It is used in `TestTransformer.java`
> on line 161.
>
> javadoc("-d", base.resolve("api").toString(),
> "-Xdoclint:none",
> "-XDaccessInternalAPI", // required to access JavacTrees
> "-doclet", "TestTransformer$MyDoclet",
> "-docletpath", System.getProperty("test.classes"),
> "-sourcepath", src.toString(),
> "p");
I confirm that `TestTransformer.java` fails as expected with an
`IllegalAccessError` if the option is not used.
java.lang.IllegalAccessError: class TestTransformer$MyDoclet (in unnamed module
@0x355de863) cannot access class com.sun.tools.javac.api.JavacTrees (in module
jdk.compiler) because module jdk.compiler does not export
com.sun.tools.javac.api to unnamed module @0x355de863
at TestTransformer$MyDoclet.run(TestTransformer.java:139)
at
jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:589)
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491538120
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v34]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision: - fix return tag name - remove debug print - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/f6d08db9..393d3a9c Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=33 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=32-33 Stats: 2 lines in 2 files changed: 0 ins; 1 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
On Thu, 15 Feb 2024 19:27:12 GMT, Jonathan Gibbons wrote: >> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java >> line 422: >> >>> 420: defaultContentCharacter(); >>> 421: } >>> 422: } >> >> Is it to pass `` through to Markdown, to allow it to deal with Markdown >> escapes? > > It is more about supporting the sequence `` ` `` so that the backtick is > treated as a literal character and not the beginning of a code span. This > is the "backstop" preferred way to ensure that a single backtick is treated > literally, without relying on detected that it is unbalanced when the end of > the current block is reached. The alternative workaround would be a single > backtick enclosed in multiple backticks, such as this ``` `` ` `` ```. (I > leave you to figure out what I actually typed there!!!) You might also need to use `` ` `` when there are two literal backticks in a sentence. After the first backtick (`), another backtick (`) can be used to delimit a code span. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491528153
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
On Thu, 15 Feb 2024 17:17:46 GMT, Pavel Rappo wrote: >> Jonathan Gibbons has updated the pull request with a new target base due to >> a merge or a rebase. The pull request now contains 44 commits: >> >> - fill in `visitRawText` in `CommentHelper.getTags` visitor >> - fixes for the "New API" page >> - change "standard" to "traditional" when referring to a comment >> - Merge remote-tracking branch 'upstream/master' into >> 8298405.doclet-markdown-v3 >> - Merge remote-tracking branch 'upstream/master' into >> 8298405.doclet-markdown-v3 >> - improve support for DocCommentParser.LineKind >> - Merge remote-tracking branch 'upstream/master' into >> 8298405.doclet-markdown-v3 # Please enter a commit message to explain why >> this merge is necessary, # especially if it merges an updated upstream into >> a topic branch. # # Lines starting with '#' will be ignored, and an empty >> message aborts # the >>commit. >> - update copyright year on test >> - refactor recent new test case in TestMarkdown.java >> - address review feedback >> - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1 > > src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java > line 422: > >> 420: defaultContentCharacter(); >> 421: } >> 422: } > > Is it to pass `` through to Markdown, to allow it to deal with Markdown > escapes? It is more about supporting the sequence `` ` `` so that the backtick is treated as a literal character and not the beginning of a code span. This is the "backstop" preferred way to ensure that a single backtick is treated literally, without relying on detected that it is unbalanced when the end of the current block is reached. The alternative workaround would be a single backtick enclosed in multiple backticks, such as this ``` `` ` `` ```. (I leave you to figure out what I actually typed there!!!) - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491519707
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
On Thu, 15 Feb 2024 17:03:09 GMT, Pavel Rappo wrote:
>> Jonathan Gibbons has updated the pull request with a new target base due to
>> a merge or a rebase. The pull request now contains 44 commits:
>>
>> - fill in `visitRawText` in `CommentHelper.getTags` visitor
>> - fixes for the "New API" page
>> - change "standard" to "traditional" when referring to a comment
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3
>> - improve support for DocCommentParser.LineKind
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3 # Please enter a commit message to explain why
>> this merge is necessary, # especially if it merges an updated upstream into
>> a topic branch. # # Lines starting with '#' will be ignored, and an empty
>> message aborts # the
>>commit.
>> - update copyright year on test
>> - refactor recent new test case in TestMarkdown.java
>> - address review feedback
>> - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
> line 1401:
>
>> 1399: */
>> 1400: enum LineKind {
>> 1401: BLANK(Pattern.compile("[ \t]*")),
>
> `BLANK` is a pseudo kind, because it is set manually, but never returned from
> `peekLine()`. I wonder if we can change it somehow.
Even if it is set manually, it is still appropriate to have it as a member in
the `LineKind` enum class.
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
> line 1433:
>
>> 1431: * @see > href="https://spec.commonmark.org/0.30/#list-items;>List items
>> 1432: */
>> 1433: BULLETED_LIST_ITEM(Pattern.compile("[-+*] .*")),
>
> This comment is about `BULLETED_LIST_ITEM` and `ORDERED_LIST_ITEM` constants.
> I know that we don't need to be very precise, but perhaps in this case we
> should. While the CommonMark spec is a vague on that, from my experiments
> with [dingus](https://spec.commonmark.org/dingus/), it appears that a list
> marker can be preceded and followed by some number of whitespace characters.
whitespace is handled separately, on line 280 (`readIndent`) and285 (`: (indent
<= 3) ? peekLineKind()`)
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491508303
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491512611
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
On Tue, 13 Feb 2024 11:15:55 GMT, Pavel Rappo wrote:
>> Jonathan Gibbons has updated the pull request with a new target base due to
>> a merge or a rebase. The pull request now contains 40 commits:
>>
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3
>> - improve support for DocCommentParser.LineKind
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3 # Please enter a commit message to explain why
>> this merge is necessary, # especially if it merges an updated upstream into
>> a topic branch. # # Lines starting with '#' will be ignored, and an empty
>> message aborts # the
>>commit.
>> - update copyright year on test
>> - refactor recent new test case in TestMarkdown.java
>> - address review feedback
>> - address review feedback
>> - added test case in TestMarkdown.java for handling of `@deprecated` tag
>> - amend comment in test
>> - improve comments on negative test case
>> - ... and 30 more: https://git.openjdk.org/jdk/compare/2ed889b7...1c64a6e0
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line
> 1021:
>
>> 1019: .findFirst();
>> 1020: if (first.isEmpty() || first.get() != tree) {
>> 1021: dct.getFirstSentence().forEach(t ->
>> System.err.println(t.getKind() + ": >>|" + t + "|<<"));
>
> Is it leftover debug output?
Oops, yes. Thanks.
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 571:
>
>> 569: // of a doclet to be specified instead of the name of the
>> 570: // doclet class and optional doclet path.
>> 571: // See https://bugs.openjdk.org/browse/JDK-8263219
>
> It's hard to understand this:
>
>> to permit an instance of an appropriately configured instance of a doclet
>
> Also: how is that piece of code used? When I commented it out, no
> test/langtools:langtools_javadoc tests failed.
1. Since forever, and still true, the way to specify a doclet is by its name,
and the tool will create the instance for you. This goes back to the original
old days before any API, when the only entry point was the command line.
This implies that (a) the doclet has a no-args constructor and (b) that all
doclet config is done through command line options. A better solution would be
to add new functionality to the various javadoc tool API (some or all of
`Main`/`Start`/`DocumentationTool`) so that a client can initialize an instance
of a doclet and pass that instance into the API.
2. If I understand the question correctly, the code is invoked by using the
command-line option `-XDaccessInternalAPI` which is a preexisting hidden
feature already supported by `javac`. It is used in `TestTransformer.java` on
line 161.
javadoc("-d", base.resolve("api").toString(),
"-Xdoclint:none",
"-XDaccessInternalAPI", // required to access JavacTrees
"-doclet", "TestTransformer$MyDoclet",
"-docletpath", System.getProperty("test.classes"),
"-sourcepath", src.toString(),
"p");
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491504223
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491502389
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v33]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: fix compilation and whitespace issues - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/2801c2e1..f6d08db9 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=32 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=31-32 Stats: 4 lines in 2 files changed: 0 ins; 0 del; 4 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 44 commits: - fill in `visitRawText` in `CommentHelper.getTags` visitor - fixes for the "New API" page - change "standard" to "traditional" when referring to a comment - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - improve support for DocCommentParser.LineKind - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit. - update copyright year on test - refactor recent new test case in TestMarkdown.java - address review feedback - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=31 Stats: 22094 lines in 197 files changed: 21411 ins; 286 del; 397 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 40 commits: - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 - improve support for DocCommentParser.LineKind - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit. - update copyright year on test - refactor recent new test case in TestMarkdown.java - address review feedback - address review feedback - added test case in TestMarkdown.java for handling of `@deprecated` tag - amend comment in test - improve comments on negative test case - ... and 30 more: https://git.openjdk.org/jdk/compare/2ed889b7...1c64a6e0 - Changes: https://git.openjdk.org/jdk/pull/16388/files Webrev: https://webrevs.openjdk.org/?repo=jdk=16388=30 Stats: 22058 lines in 194 files changed: 21390 ins; 271 del; 397 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
On Mon, 12 Feb 2024 17:27:42 GMT, Jonathan Gibbons wrote: >>> I guess it depends how much we want to import the code as-is, without >>> knowing any lint-warts. >> >> I think it would be nice not to have to modify code beyond superficial >> edits: addition of headers, renaming of packages, and converting of >> non-ASCII symbols. > > I think adding `@SuppressWarnings` is a superficial edit, but I see the > writing on the wall. Based on additional private conversations, and because the annotation is added automatically by the same utility used to address other issues in the imported code (package declarations, import statements, non-ASCII characters, etc), I will leave the annotation in at this time. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486674245
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v30]
On Mon, 12 Feb 2024 17:44:29 GMT, Pavel Rappo wrote:
>> Jonathan Gibbons has updated the pull request incrementally with one
>> additional commit since the last revision:
>>
>> refactor recent new test case in TestMarkdown.java
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
> line 1465:
>
>> 1463: markdownInput.append('\n');
>> 1464: }
>> 1465: markdownInput.append(PLACEHOLDER_BLOCK);
>
> There's quite a lot of overlap with the recently simplified
> https://github.com/openjdk/jdk/blob/7c6316886d1ae86a663d996dae373c42281622fd/src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java#L220-L238
>
> If it's impractical to factor out the common bits, maybe we could at least
> make the respective parts of HtmlDocletWriter as close as possible to those
> of MarkdownTransformer.
I think it is impractical to factor out the common bits, but I will look at the
possibility of making the code more similar -- but no promises.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486609585
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
On Mon, 12 Feb 2024 17:23:56 GMT, Pavel Rappo wrote: >> It's possible, but that would be a more global setting, whereas this is a >> very targeted modification. >> >> I guess it depends how much we want to import the code as-is, without >> knowing any lint-warts. >> >> FWIW, any module can be compiled with module-specific lint settings, if we >> choose to do so. > >> I guess it depends how much we want to import the code as-is, without >> knowing any lint-warts. > > I think it would be nice not to have to modify code beyond superficial edits: > addition of headers, renaming of packages, and converting of non-ASCII > symbols. I think adding `@SuppressWarnings` is a superficial edit, but I see the writing on the wall. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486531142
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
On Thu, 8 Feb 2024 17:20:23 GMT, Pavel Rappo wrote:
>> Jonathan Gibbons has updated the pull request with a new target base due to
>> a merge or a rebase. The pull request now contains 28 commits:
>>
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3 # Please enter a commit message to explain why
>> this merge is necessary, # especially if it
>>merges an updated upstream into a topic branch. # # Lines starting with
>> '#' will be ignored, and an empty message aborts # the commit.
>> - add test case contributed by @lahodaj
>> - initial fix for source offset problem
>> - remove unused imports
>> - First pass at remove DocCommentTransformer from the public API.
>>
>>It is still declared internally, and installed by default, using the
>> service-provider mechanism.
>>If the standard impl is not available, an identity transformer is used.
>> - updates for "first sentence" issues and tests
>> - add info about provenance of `jdk.internal.md` module
>> - MarkdownTransformer: tweak doc comments
>> - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
>> - MarkdownTransformer: use suggested text for using streams
>> - ... and 18 more: https://git.openjdk.org/jdk/compare/18e24d06...63dd8bf4
>
> src/jdk.internal.md/share/classes/module-info.java line 41:
>
>> 39: // * package and import statements are updated
>> 40: // * characters outside the ASCII range are converted to Unicode escapes
>> 41: // * @SuppressWarnings("fallthrough") is added to getSetextHeadingLevel
>
> I wonder if it would be better to compile this module without (some) lint
> checks. Is it possible?
It's possible, but that would be a more global setting, whereas this is a very
targeted modification.
I guess it depends how much we want to import the code as-is, without knowing
any lint-warts.
FWIW, any module can be compiled with module-specific lint settings, if we
choose to do so.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486450189
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v30]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: refactor recent new test case in TestMarkdown.java - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/d22668da..3f8aa6b5 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=29 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=28-29 Stats: 42 lines in 1 file changed: 1 ins; 3 del; 38 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v29]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/91588bc3..d22668da Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=28 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=27-28 Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
On Fri, 9 Feb 2024 18:27:59 GMT, Jonathan Gibbons wrote: >> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java >> line 201: >> >>> 199: } >>> 200: newline = true; >>> 201: } >> >> I can see clean LF and CRLF, but no FF; was the latter intentional? >> >> In any case, we should double-check the generated test output to see if >> there's anything unexpected. > > We've been here, with `\f` before, noting the different handling of `\f` in > `javac` and `javadoc`. > > My recollection is that it was intentional to drop support for `\f`, thus > aligning `javac` and `javadoc` behavior, and to normalize handling of the > newline sequences, translating them to `\n`. > In any case, we should double-check the generated test output to see if > there's anything unexpected. verified tests pass and no change in generated JDK API docs - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484812046
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
On Mon, 15 Jan 2024 11:48:23 GMT, Pavel Rappo wrote:
>> Jonathan Gibbons has updated the pull request with a new target base due to
>> a merge or a rebase. The incremental webrev excludes the unrelated changes
>> brought in by the merge/rebase. The pull request contains seven additional
>> commits since the last revision:
>>
>> - Merge with upstream/master
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3
>> - Address review comments
>> - Fix whitespace
>> - Improve handling of embedded inline taglets
>> - Customize support for Markdown headings
>> - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line
> 299:
>
>> 297: * @param code the code
>> 298: * @return a {@code RawTextTree} object
>> 299: * @throws IllegalArgumentException if the kind is not a recognized
>> kind for raw text
>
> This method's implementation also throws `NullPointerException` if kind is
> null, which is unusual for these methods. You can either add `@throws`, or
> workaround it by using `String.valueOf(kind)` instead of `kind.toString()`
> down in the implementation.
It took me a while to understand this comment.
For here and now, I will use `String.valueOf(kind)`
Long term, it would be good to better document `null` behavior in this API.
[JDK-8325577](https://bugs.openjdk.org/browse/JDK-8325577)
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484798682
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
On Mon, 15 Jan 2024 12:20:57 GMT, Pavel Rappo wrote: >> Jonathan Gibbons has updated the pull request with a new target base due to >> a merge or a rebase. The incremental webrev excludes the unrelated changes >> brought in by the merge/rebase. The pull request contains seven additional >> commits since the last revision: >> >> - Merge with upstream/master >> - Merge remote-tracking branch 'upstream/master' into >> 8298405.doclet-markdown-v3 >> - Address review comments >> - Fix whitespace >> - Improve handling of embedded inline taglets >> - Customize support for Markdown headings >> - JDK-8298405: Support Markdown in Documentation Comments > > src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java > line 130: > >> 128: >> 129: /** >> 130: * Create a parser for a documentation comment. > > Suggestion: > > * Creates a parser for a documentation comment. Done - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484737196
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v28]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/3b1350b2..91588bc3 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=27 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=26-27 Stats: 23 lines in 2 files changed: 4 ins; 18 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
On Mon, 15 Jan 2024 12:26:34 GMT, Pavel Rappo wrote: >> Jonathan Gibbons has updated the pull request with a new target base due to >> a merge or a rebase. The incremental webrev excludes the unrelated changes >> brought in by the merge/rebase. The pull request contains seven additional >> commits since the last revision: >> >> - Merge with upstream/master >> - Merge remote-tracking branch 'upstream/master' into >> 8298405.doclet-markdown-v3 >> - Address review comments >> - Fix whitespace >> - Improve handling of embedded inline taglets >> - Customize support for Markdown headings >> - JDK-8298405: Support Markdown in Documentation Comments > > src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java > line 201: > >> 199: } >> 200: newline = true; >> 201: } > > I can see clean LF and CRLF, but no FF; was the latter intentional? > > In any case, we should double-check the generated test output to see if > there's anything unexpected. We've been here, with `\f` before, noting the different handling of `\f` in `javac` and `javadoc`. My recollection is that it was intentional to drop support for `\f`, thus aligning `javac` and `javadoc` behavior, and to normalize handling of the newline sequences, translating them to `\n`. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484669301
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
On Sat, 13 Jan 2024 21:55:06 GMT, Pavel Rappo wrote:
>> Jonathan Gibbons has updated the pull request with a new target base due to
>> a merge or a rebase. The incremental webrev excludes the unrelated changes
>> brought in by the merge/rebase. The pull request contains seven additional
>> commits since the last revision:
>>
>> - Merge with upstream/master
>> - Merge remote-tracking branch 'upstream/master' into
>> 8298405.doclet-markdown-v3
>> - Address review comments
>> - Fix whitespace
>> - Improve handling of embedded inline taglets
>> - Customize support for Markdown headings
>> - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java
> line 257:
>
>> 255: *
>> 256: * @implSpec Visits the provided {@code RawTextTree} node
>> 257: * by calling {@code visitOther(node, p)}.
>
> Nit: for consistency with the rest of the file, reorder `@param`-`@return`
> block with the `@implSpec` tag:
>
> Suggestion:
>
> *
> * @implSpec Visits the provided {@code RawTextTree} node
> * by calling {@code visitOther(node, p)}.
> *
> * @param node the node being visited
> * @param p a parameter value
> * @return a result value
Done
> src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java line
> 1080:
>
>> 1078: }
>> 1079:
>> 1080: private String info(FileObject fo) {
>
> This does not seem to be used; is it for debugging? If so, add your `//
> DEBUG` comment.
It probably was used for debugging at some point. The method can be `static`,
meaning it is not specific to this class and could be elsewhere if we wanted to
retain the functionality. Code like this is easy enough to regenerate, so I
will delete this copy for now.
> src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java line
> 1156:
>
>> 1154:
>> 1155: /**
>> 1156: * {@return the {@linkplain ParserFactory} parser factory}.
>
> Suggestion:
>
> * {@return the {@linkplain ParserFactory} parser factory}
done
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java
> line 1065:
>
>> 1063:
>> 1064: if (accept('/')) { // (Spec. 3.7)
>> 1065: if (accept('/')) { // Markdown comment
>
> I believe that some of the changes in `com/sun/tools/javac/parser` were
> contributed by @JimLaskey. If so, don't forget to add him as a co-author:
> `/contributor add jlaskey`.
did that
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484652974
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484650198
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484651230
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484651466
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v27]
On Thu, 8 Feb 2024 23:02:18 GMT, Jonathan Gibbons wrote: >> Please review a patch to add support for Markdown syntax in documentation >> comments, as described in the associated JEP. >> >> Notable features: >> >> * support for `///` documentation comments in `JavaTokenizer` >> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` >> library >> * updates to `DocCommentParser` to treat `///` comments as Markdown >> * updates to the standard doclet to render Markdown comments in HTML > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > added test case in TestMarkdown.java for handling of `@deprecated` tag Re: https://github.com/openjdk/jdk/pull/16388#discussion_r1483182361 See https://github.com/openjdk/jdk/pull/17782 - PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1935112305
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v27]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: added test case in TestMarkdown.java for handling of `@deprecated` tag - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/cb070451..3b1350b2 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=26 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=25-26 Stats: 97 lines in 1 file changed: 91 ins; 2 del; 4 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v26]
On Thu, 8 Feb 2024 20:58:24 GMT, Jonathan Gibbons wrote:
>> Ping.
>
> I believe this is substantially covered in line 226-227. See the third call
> to `test` in the following group of lines:
>
>
> for (String src : sources) {
> test(src);
> test(src.replaceAll("@Deprecated", "/** @deprecated */"));
> test(src.replaceAll("deprecated", "notDeprecated2") // change
> class name
> .replaceAll("@Deprecated", "/// @deprecated\n"));
> }
>
>
> * The first call, `test(src)`, runs all the test cases, using the
> `@Deprecated` annotation by default. In these test cases, the name of the
> element encodes whether it is expected that the element is deprecated or not.
>
> * The second call, `test(src.replaceAll("deprecated", "notDeprecated2")`,
> runs the test cases again, after changing the annotation to a traditional
> (`/** ...*/`) comment containing the `@deprecated` tag. This is a
> long-standing call, and tests the legacy behavior of `@deprecated` appearing
> in a traditional doc comment. Effectively, it tests whether a `/**
> @deprecated */` comment has equivalent behavior to a `@Deprecated` comment.
>
> * The third call is new to this PR and the functionality to support Markdown
> comments. It makes two changes to the source for the test cases, before
> running them:
>1. as in the previous test, the annotations are replaced by a comment
> containing `@deprecated` -- except that this time, the comment is a new-style
> `/// ... ` comment instead of a traditional `/** ... */` comment, and ...
>2. because we do not expect `/// @deprecated` to indicate deprecation, we
> need to change the expected result for each test case, which we do by
> changing the element name for the test case. The change is the first call to
> replace to avoid false positives after changing the doc comment. The change
> uses a new name, `notDeprecated2`, in which `notDeprecated` encodes the
> expected deprecation status, and the `2` is to differentiate the declarations
> from other declarations in the case case that already use the name
> `notDeprecated`.
While the underlying mechanism in javac for indicating deprecation is the same
for all, I accept this is primarily a test for generated class files. I can add
a javadoc test for basic behavior of `@deprecated` in Markdown comments.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483628179
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v26]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: amend comment in test - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/c891fe9a..cb070451 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=25 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=24-25 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v25]
On Thu, 8 Feb 2024 15:37:06 GMT, Pavel Rappo wrote:
>> Ping. I do believe that it's important to have such a test.
>
> Ping.
I believe this is substantially covered in line 226-227. See the third call to
`test` in the following group of lines:
for (String src : sources) {
test(src);
test(src.replaceAll("@Deprecated", "/** @deprecated */"));
test(src.replaceAll("deprecated", "notDeprecated2") // change
class name
.replaceAll("@Deprecated", "/// @deprecated\n"));
}
* The first call, `test(src)`, runs all the test cases, using the `@Deprecated`
annotation by default. In these test cases, the name of the element encodes
whether it is expected that the element is deprecated or not.
* The second call, `test(src.replaceAll("deprecated", "notDeprecated2")`, runs
the test cases again, after changing the annotation to a traditional (`/**
...*/`) comment containing the `@deprecated` tag. This is a long-standing call,
and tests the legacy behavior of `@deprecated` appearing in a traditional doc
comment. Effectively, it tests whether a `/** @deprecated */` comment has
equivalent behavior to a `@Deprecated` comment.
* The third call is new to this PR and the functionality to support Markdown
comments. It makes two changes to the source for the test cases, before
running them:
1. as in the previous test, the annotations are replaced by a comment
containing `@deprecated` -- except that this time, the comment is a new-style
`/// ... ` comment instead of a traditional `/** ... */` comment, and ...
2. because we do not expect `/// @deprecated` to indicate deprecation, we
need to change the expected result for each test case, which we do by changing
the element name for the test case. The change is the first call to replace to
avoid false positives after changing the doc comment. The change uses a new
name, `notDeprecated2`, in which `notDeprecated` encodes the expected
deprecation status, and the `2` is to differentiate the declarations from other
declarations in the case case that already use the name `notDeprecated`.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483582480
