[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-2d-dev
Subject:    Re: [OpenJDK 2D-Dev] RFR: JDK-8272374: doclint should report missing "body" comments [v2]
From:       Jonathan Gibbons <jjg () openjdk ! java ! net>
Date:       2021-08-16 17:38:05
Message-ID: yCUKX3UFlHzs7WalGdtNHtXaU6NPIt8h9227KKUBPsQ=.f2afbe37-98eb-4708-a97c-fa37f8fac786 () github ! com
[Download RAW message or body]

> Please review a relatively simple update to have doclnt check for empty \
> "descriptions" -- the body of a doc comment, before the block tags. 
> It is already the case that doclint checks for missing/empty descriptions in block \
> tags, like @param, @return, etc. 
> There are three cases to consider:
> 
> * The comment itself is missing: this was already checked and reported as "missing \
>                 comment".
> * The comment is present, but is empty ... this seems relatively unlikely, but is \
>                 nevertheless checked and reported as "empty comment".
> * The comment is present but only has block tags. This is not always a problem, \
> since the description may be inherited, for example, in an overriding method, but \
> when it is an issue, it is reported as "no initial description".  
> No diagnostic is reported if the description is missing but the first tag is \
> `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` \
> tag for the summary. See \
> [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) \
> and the corresponding entry in the summary table to see an example of this \
> situation. 
> Diagnostics are reported if the declaration is not an overriding method and does \
> not begin with `@deprecated`.  This occurs in a number of places in the \
> `java.desktop` module, often where the doc comment is of the form `/** @return \
> _description_ */`.  To suppress those warnings for now, the `-missing` option is \
> added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of \
> this anti-pattern, look at the empty descriptions for \
> [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javas \
> e/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
>  
> Many of the doclint tests needed to be updated, because of their over-simplistic \
> minimal comments. It was not possible, in general, to avoid updating the source \
> code while preserving line numbers, so in many cases, the golden `*.out` files had \
> to be updated as well. 
> A new test is added, focussing on the different forms of empty/missing \
> descriptions, as described above.

Jonathan Gibbons has updated the pull request incrementally with one additional \
commit since the last revision:

  address review comment

-------------

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/5106/files
  - new: https://git.openjdk.java.net/jdk/pull/5106/files/60c6f569..6c875688

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=5106&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=5106&range=00-01

  Stats: 3 lines in 1 file changed: 0 ins; 1 del; 2 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5106.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5106/head:pull/5106

PR: https://git.openjdk.java.net/jdk/pull/5106


[prev in list] [next in list] [prev in thread] [next in thread]