On Fri, 26 Jan 2024 18:16:46 GMT, Jonathan Gibbons <[email protected]> wrote:
>> '--ignore-source-errors' allows generating Javadoc for the packages that
>> contain compilation errors.
>>
>> jdk.javadoc.internal.doclets.toolkit.util.ClassTree generates a type
>> hierarchy for javadoc that may include error types such as
>>
>> class Foo extends Bar {
>> }
>> ```
>> where Bar is undefined.
>>
>> The user still wants to generate documentation for Foo and have Bar as a
>> text label.
>>
>> For the unknown class Bar it is impossible to detect the enclosing
>> class/file and javadoc crashes with exception.
>>
>> This PR returns Kind.OTHER for the error types, avoiding the javadoc crash.
>
> test/langtools/jdk/javadoc/doclet/testClassTree/TestClassTree.java line 58:
>
>> 56: // Given badpkg package containing class ChildClass with an
>> undefined
>> 57: // base class, implementing undefined interface and a
>> defined
>> 58: // interface
>
> While comments are good, the comments in this method are a little strange, in
> that to understand them, you have to read them as a disjoint narrative
> composed of all the comments in the narrative. Read individually, the
> comments stand as "orphaned" phrases that do not make sense on their own.
> And, as such, they only serve to confuse the reader!
>
> If you don't want to edit the comments too much, and because this is "just"
> test code, you could maybe begin and/or end comments with an ellipsis (`...`)
> to indicate that the comment is either a continuation of what has gone before
> and/or is continued later.
Hi, those are a gherkin scenario[1] and to make things easier for a reader i
can move it out into a javadoc comment for the method.
[1] https://cucumber.io/docs/gherkin/reference/
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/17435#discussion_r1468238044
