RFR: 8333230: Improve code example in doclet package [v2]

[Hannes Wallnöfer]

On Mon, 19 Aug 2024 16:35:29 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Can I please get a review for this simple change? It's an attempt to improve the code example in doclet package.
>> Here are the generated docs with the [new code example.](https://cr.openjdk.org/~nbenalla/GeneratedDocs/newDocletExample/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html#Example.java)
>> 
>> I tried to go for simplicity while showing some features of the standard doclet, running this Doclet on a small project gives the following ouput.
>> 
>> 
>> Note: org.example.Example -> src/main/java/org/example/Example.java CLASS
>> Note: org.example.SimpleDoclet -> src/main/java/org/example/SimpleDoclet.java CLASS
>> 
>> 
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   rename SimpleDoclet to Example so that TestDocletExample.java passes

I think the new example is an improvement in some aspects, but it doesn't significantly simplify the example code, and in some other aspects it seems to add things that don't appear essential to me. 

Maybe we should define more clearly what the problem with the existing example code is, so we could either simplify the code further, or improve it in any other way that needs improvement.

One question we might ask is: do we need the example to implement custom options? It's certainly an interesting and useful feature, but it also adds a lot to the size of the code.

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java line 289:

> 287:  *
> 288:  *    // A scanner to loop through specified elements
> 289:  *    class ShowFileObjects {

What is the benefit of defining this inner class versus just implementing the `show` method in the doclet class?

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

PR Review: https://git.openjdk.org/jdk/pull/20619#pullrequestreview-2271557331
PR Review Comment: https://git.openjdk.org/jdk/pull/20619#discussion_r1738189231