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

[Jonathan Gibbons]

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

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

> 296:  *        void show(Set<? extends Element> elements) {
> 297:  *            for (Element element : elements) {
> 298:  *                if (element instanceof TypeElement te) {

It is generally discouraged to use `instanceof` on `Element`s -- use `getKind` and a cast instead.
(yes, `instanceof` works on the JDK implementation but may not work on other implementations)

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

> 297:  *            for (Element element : elements) {
> 298:  *                if (element instanceof TypeElement te) {
> 299:  *                    TreePath dct = treeUtils.getPath(te);

These days, you can use `Elements.getFileObjectOf(Element)`

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20619#discussion_r1738966779
PR Review Comment: https://git.openjdk.org/jdk/pull/20619#discussion_r1738969802