RFR: JDK-8267219: Javadoc method summary breaks when {@inheritDoc} from an empty parent [v2]

[liach]

On Mon, 17 May 2021 17:39:19 GMT, liach <github.com+7806504+liach at openjdk.org> wrote:

>> This change fixes when a method body has only inline tags that produce no output, the method summary will get eaten.
>> 
>> This change allows `{@inheritDoc}` from empty parents to go through the code path used by `-nocomment` and properly generate tables.
>> 
>> All `jtreg:test/langtools/jdk/javadoc/doclet` tests pass.
>
> liach has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR.

So I will share how I reached this as the solution than patching at somewhere else in the code path:

First, I directly modified https://github.com/openjdk/jdk/blob/894547d2c102dcbe1f9ec8a1edb11c6b31e4270e/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java#L1293 check to include the case when the contents generated by first-sentence inline tags are invalid (not just empty, so `<div class="block"></div>` would be included). However, this inserts extraneous no-break whitespaces to all-package index and fails one test.

Then, I patched at https://github.com/openjdk/jdk/blob/739769c8fc4b496f08a92225a12d07414537b6c0/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SubWriterHolderWriter.java#L145 to make it insert a no-break whitespace in order to prevent cell deletion. However, this breaks `-nocomment`, and I figured that reusing `-nocomment`'s code path would be the best approach as a result, which is the current PR.

----------
> (1) Why does the lower level that prints out HTML leave out pieces of structure?

https://github.com/openjdk/jdk/blob/894547d2c102dcbe1f9ec8a1edb11c6b31e4270e/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Table.java#L330-L331

It's done by this piece of code afai see.

> (2) Why does the higher level that creates this structure knows about and works around that behavior of the lower level?

This would be more fascinating. In that method, there is a whitespace insertion, which is used for like methods without `/** */` comments. So there are two ways to handle the empty comments, and I find out for resolving this issue, reusing the one used by `-nocomment` is easier and more compatible than reusing that used by regular empty methods.

--------

So this check in `Table` introduced in [JDK-8256580](https://bugs.openjdk.java.net/browse/JDK-8256580) (#1438) might have been the culprit.

If we seek a more comprehensive change, I personally would keep the change introduced in 8256580 and remove the original no-break whitespace insertion, so we consistently yield empty content for empty comments, and we can then properly handle these empty comments downstream.

What are your thoughts?

Another update: just checked 8256580, and the problem is exactly the same as what we see here.

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

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