RFR: 8242564: javadoc crashes:: class cast exeception com.sun.tools.javac.code.Symtab$6

[Vladimir Petko]

On Fri, 26 Jan 2024 18:16:46 GMT, Jonathan Gibbons <jjg at openjdk.org> 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