Re: RFR: JDK-8288368: simplify code in ValueTaglet, remove redundant code

2022-06-14 Thread Pavel Rappo
On Mon, 13 Jun 2022 23:57:45 GMT, Jonathan Gibbons wrote: > Please review an almost trivial cleanup change, to eliminate the call to an > ill-considered method in Utils, and then remove the method itself. > > Verified that there is no significant change in the generated docs as a > result off

Re: RFR: JDK-8281445: Document the default value for the override-methods option

2022-06-10 Thread Pavel Rappo
On Fri, 10 Jun 2022 02:59:29 GMT, Jonathan Gibbons wrote: > Please refer a trivial update for the javadoc command-line help, to specify > the default value for the --override-methods option. Marked as reviewed by prappo (Reviewer). - PR: https://git.openjdk.org/jdk19/pull/2

Integrated: 8287333: Clean up ParamTaglet and ThrowsTaglet

2022-06-08 Thread Pavel Rappo
On Wed, 25 May 2022 15:39:10 GMT, Pavel Rappo wrote: > A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only > copies one instance of the specified exception. This pull request has now been integrated. Changeset: 024a240e Author: Pavel Rappo URL:

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v6]

2022-06-08 Thread Pavel Rappo
On Tue, 7 Jun 2022 20:36:26 GMT, Pavel Rappo wrote: >> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only >> copies one instance of the specified exception. > > Pavel Rappo has updated the pull request with a new target base due to a > merge

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v6]

2022-06-07 Thread Pavel Rappo
On Tue, 7 Jun 2022 13:38:48 GMT, Pavel Rappo wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java >> line 94: >> >>> 92: ? ee.getTypeParameters() >>> 93: : ee.getPara

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v6]

2022-06-07 Thread Pavel Rappo
On Tue, 7 Jun 2022 06:14:13 GMT, Jonathan Gibbons wrote: > Noted about tagId. You could still do a local cleanup for the type of the > map, but I guess we'll wait and see what your plan is. I cleaned up locally in 453ecbe. Mind you, the "deeper refactoring" is tracked by JDK-8285488.

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v6]

2022-06-07 Thread Pavel Rappo
> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only > copies one instance of the specified exception. Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 37 commits: - Merge branch '

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v5]

2022-06-07 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:19:09 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 35 commits: >> >> - Merge branch 'master' into 8287333 >> >>It'

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v5]

2022-06-07 Thread Pavel Rappo
On Tue, 7 Jun 2022 05:45:54 GMT, Jonathan Gibbons wrote: >> Hm... Which kind of "Error" would be thrown for which "other type"? I don't >> think that this method is ever called with an element other than a >> constructor or method; look: >> >> public ThrowsTaglet() { >>

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v5]

2022-06-07 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:40:18 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 35 commits: >> >> - Merge branch 'master' into 8287333 >> >>It'

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v5]

2022-06-07 Thread Pavel Rappo
> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only > copies one instance of the specified exception. Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 35 commits: - Merge branch '

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v4]

2022-06-06 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:43:11 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 33 commits: >> >> - Merge branch 'master' into 8287333 >> >>Thi

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v3]

2022-06-06 Thread Pavel Rappo
On Mon, 6 Jun 2022 21:27:25 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request incrementally with three additional >> commits since the last revision: >> >> - Remove upper-bounded wildcard >> >>This change simpl

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v4]

2022-06-06 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:50:05 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 33 commits: >> >> - Merge branch 'master' into 8287333 >> >>Thi

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v4]

2022-06-06 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:39:10 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 33 commits: >> >> - Merge branch 'master' into 8287333 >> >>Thi

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v4]

2022-06-06 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:27:07 GMT, Jonathan Gibbons wrote: > It does more than just warn ... What else beyond converting `ParamTree`s to `Content` and warning authors about unexpected `ParamTree` does it do? Separately. Could it be that you haven't seen further commits? GitHub does not seem to

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v4]

2022-06-06 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:24:08 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 33 commits: >> >> - Merge branch 'master' into 8287333 >> >>Thi

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v4]

2022-06-06 Thread Pavel Rappo
On Mon, 6 Jun 2022 20:22:34 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 33 commits: >> >> - Merge branch 'master' into 8287333 >> >>Thi

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v4]

2022-06-05 Thread Pavel Rappo
> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only > copies one instance of the specified exception. Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 33 commits: - Merge branch '

Integrated: 8287753: [spelling] close well-established compounds

2022-06-04 Thread Pavel Rappo
On Thu, 2 Jun 2022 22:48:56 GMT, Pavel Rappo wrote: > This is a spelling and terminology PR, not a code PR. Rationale for some of > the changes are as follows: > > * "Subsignature" is mentioned in JLS 8.4.2 Method Signature. > * lower- and upper- bounded wrt `super` an

Re: RFR: JDK-8252717: Integrate/merge legacy standard doclet diagnostics and doclint

2022-06-03 Thread Pavel Rappo
On Thu, 2 Jun 2022 20:59:26 GMT, Jonathan Gibbons wrote: > Please review a moderate change to enable (most) doclet warnings even if > doclint is enabled. > > Since the introduction of doclint, there was some (small) overlap between the > small set of warnings generated by the doclet and the

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v3]

2022-06-03 Thread Pavel Rappo
> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only > copies one instance of the specified exception. Pavel Rappo has updated the pull request incrementally with three additional commits since the last revision: - Remove upper-bounded wildcard This

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v2]

2022-06-03 Thread Pavel Rappo
On Fri, 3 Jun 2022 11:34:52 GMT, Pavel Rappo wrote: >> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only >> copies one instance of the specified exception. > > Pavel Rappo has updated the pull request with a new target base due to a > merge or a re

Re: RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v2]

2022-06-03 Thread Pavel Rappo
> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only > copies one instance of the specified exception. Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes b

Re: RFR: JDK-8252717: Integrate/merge legacy standard doclet diagnostics and doclint

2022-06-03 Thread Pavel Rappo
On Thu, 2 Jun 2022 20:59:26 GMT, Jonathan Gibbons wrote: > Please review a moderate change to enable (most) doclet warnings even if > doclint is enabled. > > Since the introduction of doclint, there was some (small) overlap between the > small set of warnings generated by the doclet and the

RFR: 8287753: [spelling] close well-established compounds

2022-06-02 Thread Pavel Rappo
This is a spelling and terminology PR, not a code PR. Rationale for some of the changes are as follows: * "Subsignature" is mentioned in JLS 8.4.2 Method Signature. * lower- and upper- bounded wrt `super` and `extends` are mentioned in JLS 4.10.5 Type Projections. * For "super super class" I

Re: RFR: JDK-8287606: standardize spelling of subtype and supertype etc in comments

2022-06-02 Thread Pavel Rappo
On Wed, 1 Jun 2022 05:20:22 GMT, Jonathan Gibbons wrote: > Please review a trivial fix to remove unnecessary hyphens from compound words > in comments, > as suggested in an earlier review. Looks okay; thanks. This PR changes hyphenated forms to closed forms. Consider also changing open forms

Re: RFR: JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section [v3]

2022-05-30 Thread Pavel Rappo
On Wed, 25 May 2022 20:55:21 GMT, Jonathan Gibbons wrote: >> As described in the JBS issue, the observed problem is a side-effect of a >> related but different issue, which is that record classes are not treated >> the same was as enum classes when it comes to generating the class hierarchy

Re: RFR: JDK-8277420: Provide a way to copy the hyperlink to a doc element to the clipboard [v3]

2022-05-27 Thread Pavel Rappo
On Fri, 27 May 2022 07:16:23 GMT, Hannes Wallnöfer wrote: >> This is a CSS/JavaScript only change to implement copy-to-clipboard >> functionality for all headers (`h1` - `h6`) that have an `id` attribute >> associated with them. The following element-attribute patterns are supported >> (using

Re: RFR: JDK-8277420: Provide a way to copy the hyperlink to a doc element to the clipboard [v2]

2022-05-26 Thread Pavel Rappo
On Mon, 23 May 2022 19:09:41 GMT, Hannes Wallnöfer wrote: >> This is a CSS/JavaScript only change to implement copy-to-clipboard >> functionality for all headers (`h1` - `h6`) that have an `id` attribute >> associated with them. The following element-attribute patterns are supported >> (using

Re: RFR: JDK-8277420: Provide a way to copy the hyperlink to a doc element to the clipboard [v2]

2022-05-26 Thread Pavel Rappo
On Mon, 23 May 2022 19:09:41 GMT, Hannes Wallnöfer wrote: >> This is a CSS/JavaScript only change to implement copy-to-clipboard >> functionality for all headers (`h1` - `h6`) that have an `id` attribute >> associated with them. The following element-attribute patterns are supported >> (using

Re: RFR: JDK-8279513: jdk/javadoc/doclet/testDocletExample/TestDocletExample.java fails after 8278795

2022-05-25 Thread Pavel Rappo
On Thu, 19 May 2022 22:05:50 GMT, Jonathan Gibbons wrote: > Please review a test-only fix to make a recent new test more robust. > > The test was not fundamentally broken, so the essential functionality remains > the same. However, it does assume access to the `src/jdk.javadoc` directory, >

Re: RFR: JDK-8279513: jdk/javadoc/doclet/testDocletExample/TestDocletExample.java fails after 8278795

2022-05-25 Thread Pavel Rappo
On Wed, 25 May 2022 16:59:25 GMT, Jonathan Gibbons wrote: >> test/langtools/jdk/javadoc/doclet/testDocletExample/TestDocletExample.java >> line 71: >> >>> 69: var entryPointSnippet = snippets.getSnippetById(dc, >>> "entry-point"); >>> 70: if (entryPointSnippet == null) { >>>

Re: RFR: JDK-8279513: jdk/javadoc/doclet/testDocletExample/TestDocletExample.java fails after 8278795

2022-05-25 Thread Pavel Rappo
On Wed, 25 May 2022 17:02:15 GMT, Jonathan Gibbons wrote: > `SnippetUtils` is broken if we get a null result. If it's unconditionally so, which it seems to be, wouldn't it be better to throw something from `SnippetUtils.getSnippetById` instead? - PR:

Re: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package [v3]

2022-05-25 Thread Pavel Rappo
On Wed, 25 May 2022 17:00:16 GMT, Jonathan Gibbons wrote: >> Please review a small fix to address use of snippets in source code in the >> unnamed package. >> >> The core of the fix is to replace `packageName(pkg, utils)` (which returns >> `""` for the unnamed package) with plain old >>

RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet

2022-05-25 Thread Pavel Rappo
A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only copies one instance of the specified exception. - Commit messages: - Update top-level doc comment - Trivially re-order assignments - Reformat for clarity - Remove dead condition - Remove emptiness check

Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v5]

2022-05-24 Thread Pavel Rappo
On Tue, 24 May 2022 19:50:41 GMT, Jonathan Gibbons wrote: >> Please review the code and tests to add support for a new `@spec url title` >> tag to javadoc. Note, this does not include any changes to API doc comments >> to use the new tag in JDK API documentation; that will come later. > >

Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v5]

2022-05-24 Thread Pavel Rappo
On Tue, 24 May 2022 21:29:53 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 seven commits: >> >> - Merge remote-tracking branch 'upstream/master' into 6251738.

Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v5]

2022-05-24 Thread Pavel Rappo
On Tue, 24 May 2022 19:50:41 GMT, Jonathan Gibbons wrote: >> Please review the code and tests to add support for a new `@spec url title` >> tag to javadoc. Note, this does not include any changes to API doc comments >> to use the new tag in JDK API documentation; that will come later. > >

Re: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package [v2]

2022-05-24 Thread Pavel Rappo
On Mon, 16 May 2022 23:16:25 GMT, Jonathan Gibbons wrote: >> Please review a small fix to address use of snippets in source code in the >> unnamed package. >> >> The core of the fix is to replace `packageName(pkg, utils)` (which returns >> `""` for the unnamed package) with plain old >>

Re: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package [v2]

2022-05-24 Thread Pavel Rappo
On Mon, 16 May 2022 22:54:55 GMT, Jonathan Gibbons wrote: >> Going forward, how about an `Args` builder, with fluent methods >> `add(String)`, `addAll(String...)`, `addAll(List)` and >> `add(Optional)` ... although that last one will cause warnings from >> javac which grumbles about using

Re: RFR: JDK-8286101: Support formatting in @value tag [v3]

2022-05-24 Thread Pavel Rappo
On Tue, 17 May 2022 23:14:48 GMT, Jonathan Gibbons wrote: >> This PR is for an update to the doc comment `{@value}` tag to permit an >> optional [format >> string](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Formatter.html#syntax) >> after the name of the tag. >>

Re: RFR: JDK-8279513: jdk/javadoc/doclet/testDocletExample/TestDocletExample.java fails after 8278795

2022-05-24 Thread Pavel Rappo
On Thu, 19 May 2022 22:05:50 GMT, Jonathan Gibbons wrote: > Please review a test-only fix to make a recent new test more robust. > > The test was not fundamentally broken, so the essential functionality remains > the same. However, it does assume access to the `src/jdk.javadoc` directory, >

Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v4]

2022-05-24 Thread Pavel Rappo
On Wed, 18 May 2022 18:43:44 GMT, Jonathan Gibbons wrote: >> Please review the code and tests to add support for a new `@spec url title` >> tag to javadoc. Note, this does not include any changes to API doc comments >> to use the new tag in JDK API documentation; that will come later. > >

Re: RFR: JDK-8286832: JavaDoc pages call browser history API too often

2022-05-23 Thread Pavel Rappo
On Tue, 17 May 2022 13:48:25 GMT, Hannes Wallnöfer wrote: > This is a small but important fix in our browser script that ensures that the > `history.replaceState()` function is not called repeatedly during scrolling. > The existing code makes sure the function is called no more often then

Re: RFR: JDK-8286887: Remove logging from search.js

2022-05-23 Thread Pavel Rappo
On Tue, 17 May 2022 14:13:38 GMT, Hannes Wallnöfer wrote: > This is a trivial change to remove a logging statement in search.js that > sneaked in with JDK-8248863. Marked as reviewed by prappo (Reviewer). Marked as reviewed by prappo (Reviewer). - PR:

Re: RFR: JDK-8286832: JavaDoc pages call browser history API too often

2022-05-23 Thread Pavel Rappo
On Tue, 17 May 2022 13:48:25 GMT, Hannes Wallnöfer wrote: > This is a small but important fix in our browser script that ensures that the > `history.replaceState()` function is not called repeatedly during scrolling. > The existing code makes sure the function is called no more often then

Integrated: 8287099: Clean up terminology regarding doc comment descriptions.

2022-05-21 Thread Pavel Rappo
On Fri, 20 May 2022 20:55:02 GMT, Pavel Rappo wrote: > Use the term "main description". This pull request has now been integrated. Changeset: 7c086475 Author: Pavel Rappo URL: https://git.openjdk.java.net/jdk/commit/7c0864752aa6301ec5a2123a5a96eb71bc0a83af Stats:

RFR: 8287099: Clean up terminology regarding doc comment descriptions.

2022-05-20 Thread Pavel Rappo
Use the term "main description". - Commit messages: - Update copyright years - Initial commit Changes: https://git.openjdk.java.net/jdk/pull/8818/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk=8818=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8287099 Stats: 11

Re: RFR: JDK-8286101: Support formatting in @value tag

2022-05-17 Thread Pavel Rappo
On Thu, 5 May 2022 23:39:46 GMT, Jonathan Gibbons wrote: > This PR is for an update to the doc comment `{@value}` tag to permit an > optional [format > string](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Formatter.html#syntax) > after the name of the tag. > >

Re: RFR: JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section

2022-05-16 Thread Pavel Rappo
On Tue, 3 May 2022 20:38:44 GMT, Jonathan Gibbons wrote: > As described in the JBS issue, the observed problem is a side-effect of a > related but different issue, which is that record classes are not treated the > same was as enum classes when it comes to generating the class hierarchy in >

Re: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package

2022-05-16 Thread Pavel Rappo
On Fri, 13 May 2022 21:51:32 GMT, Jonathan Gibbons wrote: > Please review a small fix to address use of snippets in source code in the > unnamed package. > > The core of the fix is to replace `packageName(pkg, utils)` (which returns > `""` for the unnamed package) with plain old >

Re: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated.

2022-05-13 Thread Pavel Rappo
On Thu, 12 May 2022 23:10:36 GMT, Jonathan Gibbons wrote: > > What's that `-XDdummy=dummy` you use in tests? > > It's a no-op placeholder. JavaDoc does not allow empty arguments, and the > alternative is dynamically build a list with a conditional component. `-XD` > is a "hidden" option to

Re: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated.

2022-05-13 Thread Pavel Rappo
On Fri, 6 May 2022 22:06:17 GMT, Jonathan Gibbons wrote: > Please review a simple small change to `TagletManager`, to not report > warnings about bad use of tags (such as `@author` and `@version`) when > command-line options have not been given to enable the use of the tags in the > output

Re: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated.

2022-05-06 Thread Pavel Rappo
On Fri, 6 May 2022 22:06:17 GMT, Jonathan Gibbons wrote: > Please review a simple small change to `TagletManager`, to not report > warnings about bad use of tags (such as `@author` and `@version`) when > command-line options have not been given to enable the use of the tags in the > output

Re: RFR: JDK-8286153: Remove redundant casts and other cleanup [v2]

2022-05-05 Thread Pavel Rappo
On Thu, 5 May 2022 17:20:25 GMT, Jonathan Gibbons wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all >> been removed. Various other warnings and suggestions were made by the IDE

Re: RFR: JDK-8286153: Remove redundant casts and other cleanup

2022-05-05 Thread Pavel Rappo
On Thu, 5 May 2022 10:30:17 GMT, Pavel Rappo wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all >> been removed. Various other warnings and suggesti

Re: RFR: JDK-8286153: Remove redundant casts and other cleanup

2022-05-05 Thread Pavel Rappo
On Thu, 5 May 2022 00:18:56 GMT, Jonathan Gibbons wrote: > Please review some cleanup updates to address issues reported by an IDE. > > The seeds for the change were a series of redundant casts, that have now all > been removed. Various other warnings and suggestions were made by the IDE >

Integrated: 8285470: Improve handling of @inheritDoc

2022-05-04 Thread Pavel Rappo
On Fri, 22 Apr 2022 14:05:44 GMT, Pavel Rappo wrote: > The only taglet that along with its own tag needs to know the immediately > enclosing tag is `InheritDocTaglet`: > > @return {@inheritDoc} > @throws NullPointerException {@inheritDoc} > @param p {@inheri

Re: RFR: 8285470: Improve handling of @inheritDoc [v4]

2022-05-04 Thread Pavel Rappo
On Tue, 3 May 2022 19:30:01 GMT, Pavel Rappo wrote: >> The only taglet that along with its own tag needs to know the immediately >> enclosing tag is `InheritDocTaglet`: >> >> @return {@inheritDoc} >> @throws NullPointerException {@inheritDoc

Re: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v3]

2022-05-04 Thread Pavel Rappo
On Tue, 3 May 2022 22:47:49 GMT, Jonathan Gibbons wrote: >> Please review some localized cleanup for the doclint Checker class, >> primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one >> switch statement

Re: RFR: JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section

2022-05-04 Thread Pavel Rappo
On Tue, 3 May 2022 20:38:44 GMT, Jonathan Gibbons wrote: > As described in the JBS issue, the observed problem is a side-effect of a > related but different issue, which is that record classes are not treated the > same was as enum classes when it comes to generating the class hierarchy in >

Re: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2]

2022-05-03 Thread Pavel Rappo
On Tue, 3 May 2022 22:30:51 GMT, Jonathan Gibbons wrote: > Yes, but RECORD is handled in a different case, along with METHOD and > CONSTRUCTOR, because it can have "plain" `@param` as well as type-parameter > `@param`. In contrast, a class or interface can only have type-parameter > `@param`

Re: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2]

2022-05-03 Thread Pavel Rappo
On Tue, 3 May 2022 21:53:21 GMT, Jonathan Gibbons wrote: >> Please review some localized cleanup for the doclint Checker class, >> primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one >> switch statement

Re: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2]

2022-05-03 Thread Pavel Rappo
On Tue, 3 May 2022 21:53:21 GMT, Jonathan Gibbons wrote: >> Please review some localized cleanup for the doclint Checker class, >> primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one >> switch statement

Re: RFR: 8285470: Improve handling of @inheritDoc [v4]

2022-05-03 Thread Pavel Rappo
d > * `InheritDocTaglet` receives its own tag, not the tag that encloses it Pavel Rappo 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 ten additiona

Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)

2022-05-03 Thread Pavel Rappo
On Thu, 28 Apr 2022 02:05:47 GMT, Jonathan Gibbons wrote: > Please review the code and tests to add support for a new `@spec url title` > tag to javadoc. Note, this does not include any changes to API doc comments > to use the new tag in JDK API documentation; that will come later. This is

Re: RFR: JDK-8285869: Selective cleanup in doclint Checker class

2022-05-03 Thread Pavel Rappo
On Fri, 29 Apr 2022 00:29:50 GMT, Jonathan Gibbons wrote: > Please review some localized cleanup for the doclint Checker class, primarily > focused on upgrading to the use of "enhanced `switch`" > > The output of one test was changed because of some improvements in one switch > statement to

Re: RFR: 8285470: Improve handling of @inheritDoc [v3]

2022-04-26 Thread Pavel Rappo
On Mon, 25 Apr 2022 23:12:43 GMT, Jonathan Gibbons wrote: > This one is somewhat questionable. > > Generally, the trees in `javac` and `javadoc` do not store parent pointers > (to save space), leading to a general coding philosophy of "collect any > necessary information as you walk down the

Re: RFR: 8285611: Retrofit (Doc)Pretty with java.io.UncheckedIOException

2022-04-26 Thread Pavel Rappo
On Mon, 25 Apr 2022 21:01:58 GMT, Pavel Rappo wrote: > Standard `java.io.UncheckedIOException` is more convenient than older ad-hoc > `com.sun.tools.javac.tree.(Doc)Pretty.UncheckedIOException`. Addressing your earlier points after integration. > 1. To be clear, this is more

Integrated: 8285611: Retrofit (Doc)Pretty with java.io.UncheckedIOException

2022-04-26 Thread Pavel Rappo
On Mon, 25 Apr 2022 21:01:58 GMT, Pavel Rappo wrote: > Standard `java.io.UncheckedIOException` is more convenient than older ad-hoc > `com.sun.tools.javac.tree.(Doc)Pretty.UncheckedIOException`. This pull request has now been integrated. Changeset: e333cd33 Author: Pavel Rapp

RFR: 8285611: Retrofit (Doc)Pretty with java.io.UncheckedIOException

2022-04-25 Thread Pavel Rappo
Standard `java.io.UncheckedIOException` is more convenient than older ad-hoc `com.sun.tools.javac.tree.(Doc)Pretty.UncheckedIOException`. - Commit messages: - Initial commit Changes: https://git.openjdk.java.net/jdk/pull/8387/files Webrev:

Withdrawn: 8285396: Do not fill in the stacktrace of an internal exception

2022-04-25 Thread Pavel Rappo
On Thu, 21 Apr 2022 19:28:08 GMT, Pavel Rappo wrote: > Sometimes an exception is retrofitted into control flow to interrupt it in a > way that it wasn't originally designed to be interrupted. Such an exception > is an implementation detail. Once the exception is caught i

Re: RFR: 8285396: Do not fill in the stacktrace of an internal exception [v2]

2022-04-25 Thread Pavel Rappo
On Thu, 21 Apr 2022 23:28:16 GMT, Pavel Rappo wrote: >> Sometimes an exception is retrofitted into control flow to interrupt it in a >> way that it wasn't originally designed to be interrupted. Such an exception >> is an implementation detail. Once the exception is

Re: RFR: JDK-8267690: Revisit (Doc)Tree search implemented by throwing an exception [v2]

2022-04-25 Thread Pavel Rappo
On Mon, 25 Apr 2022 19:03:35 GMT, Jonathan Gibbons wrote: >> Please review a moderately simple cleanup change, to eliminate using an >> exception to terminate scanning a `Tree` or `DocTree` in >> `(Doc)TreePath.getPath`. >> >> The change is to set a field with the intended result, and once

Re: RFR: JDK-8267690: Revisit (Doc)Tree search implemented by throwing an exception

2022-04-25 Thread Pavel Rappo
On Fri, 22 Apr 2022 19:10:38 GMT, Jonathan Gibbons wrote: > Please review a moderately simple cleanup change, to eliminate using an > exception to terminate scanning a `Tree` or `DocTree` in > `(Doc)TreePath.getPath`. > > The change is to set a field with the intended result, and once that

Re: RFR: JDK-8267690: Revisit (Doc)Tree search implemented by throwing an exception

2022-04-25 Thread Pavel Rappo
On Fri, 22 Apr 2022 19:10:38 GMT, Jonathan Gibbons wrote: > Please review a moderately simple cleanup change, to eliminate using an > exception to terminate scanning a `Tree` or `DocTree` in > `(Doc)TreePath.getPath`. > > The change is to set a field with the intended result, and once that

Re: RFR: 8285470: Improve handling of @inheritDoc [v3]

2022-04-22 Thread Pavel Rappo
d > * `InheritDocTaglet` receives its own tag, not the tag that encloses it Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision: Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java

Re: RFR: 8285470: Improve handling of @inheritDoc [v2]

2022-04-22 Thread Pavel Rappo
d > * `InheritDocTaglet` receives its own tag, not the tag that encloses it Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision: (fix) Fix a test failure Fixes a failure in jdk/javadoc/doclet/testInheritDocWithinInappropriate

RFR: 8285470: Improve handling of @inheritDoc

2022-04-22 Thread Pavel Rappo
The only taglet that along with its own tag needs to know the immediately enclosing tag is `InheritDocTaglet`: @return {@inheritDoc} @throws NullPointerException {@inheritDoc} @param p {@inheritDoc} However, the immediately enclosing tag is unconditionally passed to all taglets. If

Re: RFR: 8285396: Do not fill in the stacktrace of an internal exception [v2]

2022-04-21 Thread Pavel Rappo
tacktrace. Filling in a stacktrace is not free. Filling > in a stacktrace that won't be used seems like a waste. Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision: Address feedback - Changes: - all: https://git.openjdk.j

Re: RFR: 8285396: Do not fill in the stacktrace of an internal exception [v2]

2022-04-21 Thread Pavel Rappo
On Thu, 21 Apr 2022 22:10:36 GMT, Pavel Rappo wrote: > The changes for the `UncheckedIOException` wrappers look OK, but might be > even better if the code properly unwrapped the wrapper and simply rethrew the > underlying cause. For example, > > replace > >

Re: RFR: 8285396: Do not fill in the stacktrace of an internal exception

2022-04-21 Thread Pavel Rappo
On Thu, 21 Apr 2022 20:34:31 GMT, Jonathan Gibbons wrote: > The changes for the `UncheckedIOException` wrappers look OK, but might be > even better if the code properly unwrapped the wrapper and simply rethrew the > underlying cause. For example, > > replace > > ``` > } catch

RFR: 8285396: Do not fill in the stacktrace of an internal exception

2022-04-21 Thread Pavel Rappo
Sometimes an exception is retrofitted into control flow to interrupt it in a way that it wasn't originally designed to be interrupted. Such an exception is an implementation detail. Once the exception is caught internally, it is discarded. An exception has a stacktrace. Filling in a stacktrace

Integrated: 8284908: Refine diagnostic positions for DCErroneous

2022-04-21 Thread Pavel Rappo
On Fri, 15 Apr 2022 16:58:55 GMT, Pavel Rappo wrote: > Before: > > Standard Doclet version 18+36-2087 > Building tree for all the packages and classes... > Generating /tmp/whatever/ExampleDiagnostics.html... > ExampleDiagnostics.java:5: error: unexpected content

Re: RFR: 8284908: Refine diagnostic positions for DCErroneous [v3]

2022-04-20 Thread Pavel Rappo
^ > ExampleDiagnostics.java:17: error: '>' expected > * @param ^ Pavel Rappo 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 requ

Re: RFR: 8284908: Refine diagnostic positions for DCErroneous [v2]

2022-04-20 Thread Pavel Rappo
On Wed, 20 Apr 2022 21:45:51 GMT, Jonathan Gibbons wrote: >> Pavel Rappo has updated the pull request incrementally with one additional >> commit since the last revision: >> >> Address feedback > > test/langtools/tools/javac/doctree/DocCommentT

Re: RFR: 8284908: Refine diagnostic positions for DCErroneous [v2]

2022-04-20 Thread Pavel Rappo
^ > ExampleDiagnostics.java:17: error: '>' expected > * @param ^ Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision: Address feedback - Changes: - all: https://git.openjdk.java.net/jdk/pull/

Integrated: 8284697: Avoid parsing the doc comment of an element that is not documented

2022-04-19 Thread Pavel Rappo
On Fri, 15 Apr 2022 18:23:38 GMT, Pavel Rappo wrote: > We shouldn't parse comments that are going to be thrown away. > > Although the change is simple, I have no idea on how to test it. So I'm > tempted to affix the "noreg-other" or "noreg-hard" label on the J

Re: RFR: 8284697: Avoid parsing the doc comment of an element that is not documented

2022-04-18 Thread Pavel Rappo
On Sat, 16 Apr 2022 20:52:42 GMT, Jonathan Gibbons wrote: > The way to test it would be to put errors into a doc comment, and verify that > no errors are reported, strongly implying the comment was not parse Although we could do that, we should also keep in mind that those errors weren't

Re: RFR: 8284697: Avoid parsing the doc comment of an element that is not documented

2022-04-15 Thread Pavel Rappo
On Fri, 15 Apr 2022 19:56:21 GMT, Pavel Rappo wrote: > > Does this need a jmh benchmark? > > I'm not sure how to compare "before" and "after" meaningfully here. Generally > speaking, I was satisfied when saw that `time` output stayed the same on my

Re: RFR: 8284697: Avoid parsing the doc comment of an element that is not documented

2022-04-15 Thread Pavel Rappo
On Fri, 15 Apr 2022 19:08:20 GMT, XenoAmess wrote: > Does this need a jmh benchmark? I'm not sure how to compare "before" and "after" meaningfully here. Generally speaking, I was satisfied when saw that `time` output stayed the same on my machine; maybe only a few seconds different on a

RFR: 8284697: Avoid parsing the doc comment of an element that is not documented

2022-04-15 Thread Pavel Rappo
We shouldn't parse comments that are going to be thrown away. Although the change is simple, I have no idea on how to test it. So I'm tempted to affix the "noreg-other" or "noreg-hard" label on the JBS issue. - Commit messages: - Reorder checks Changes:

Re: RFR: 8284908: Refine diagnostic positions for DCErroneous

2022-04-15 Thread Pavel Rappo
On Fri, 15 Apr 2022 16:58:55 GMT, Pavel Rappo wrote: > Before: > > Standard Doclet version 18+36-2087 > Building tree for all the packages and classes... > Generating /tmp/whatever/ExampleDiagnostics.html... > ExampleDiagnostics.java:5: error: unexpected content

RFR: 8284908: Refine diagnostic positions for DCErroneous

2022-04-15 Thread Pavel Rappo
Before: Standard Doclet version 18+36-2087 Building tree for all the packages and classes... Generating /tmp/whatever/ExampleDiagnostics.html... ExampleDiagnostics.java:5: error: unexpected content * {@docRoot a} ^ ExampleDiagnostics.java:11: error: unexpected content *

Integrated: 8283864: Clean up DocFinder and friends

2022-04-14 Thread Pavel Rappo
On Wed, 13 Apr 2022 18:02:14 GMT, Pavel Rappo wrote: > A clean-up to facilitate more clean-up in the future. This pull request has now been integrated. Changeset: 1cc3c330 Author: Pavel Rappo URL: https://git.openjdk.java.net/jdk/commit/1cc3c330e3223944d2e20b3721ef336c87511e34 St

Re: RFR: 8283864: Clean up DocFinder and friends

2022-04-14 Thread Pavel Rappo
On Wed, 13 Apr 2022 18:02:14 GMT, Pavel Rappo wrote: > A clean-up to facilitate more clean-up in the future. I'm testing the most recent commit, 7bc2fe3. If the tests pass, I'll integrate this PR. - PR: https://git.openjdk.java.net/jdk/pull/8229

Re: RFR: 8283864: Clean up DocFinder and friends [v2]

2022-04-14 Thread Pavel Rappo
> A clean-up to facilitate more clean-up in the future. Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision: Address feedback - Changes: - all: https://git.openjdk.java.net/jdk/pull/8229/files - new: ht

Re: RFR: 8283864: Clean up DocFinder and friends

2022-04-14 Thread Pavel Rappo
On Wed, 13 Apr 2022 23:23:53 GMT, Jonathan Gibbons wrote: >> A clean-up to facilitate more clean-up in the future. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java > line 136: > >> 134: } >> 135: >> 136: private Input copy(Utils utils)

Re: RFR: 8283864: Clean up DocFinder and friends

2022-04-14 Thread Pavel Rappo
On Thu, 14 Apr 2022 11:41:59 GMT, Pavel Rappo wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java >> line 112: >> >>> 110: assert !(e instanceof TypeElement typeElement) >>> 111:

  1   2   3   4   5   6   7   >