On Mon, 17 May 2021 17:39:19 GMT, liach <github.com+7806504+li...@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
