can javadoc have a mode easier and direct design?

[david Grajales]

Hello everyone,

I recently saw the efforts to improve Javadoc with a dark theme (great
news!). However, I believe an even bigger step forward would be to rethink
the overall structure of Javadoc pages to make them easier to read and more
practical.

For instance, let’s compare the StringBuilder documentation in Java with
its equivalent in C#:

   -

   Java:
   https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html
   -

   C#:
   https://learn.microsoft.com/es-es/dotnet/standard/base-types/stringbuilder

The Javadoc version doesn’t provide code examples for method usage, whereas
the C# documentation includes multiple illustrative snippets. These
examples are incredibly useful for developers to understand APIs at a
glance.

Similarly, if we look at Python’s documentation:

   -

   https://www.pydocs.site/es/native-functions/string-methods/

We see shorter text, more inline code, and explanations that are often
embedded directly in the code comments. This makes the content feel
lighter, more approachable, and easier to navigate.

My question is:

   -

   Is there any initiative to include more usage examples and concise,
   code-centric explanations in Javadoc?
   -

   Or, is there an alternative *official* documentation site that already
   follows this more example-driven approach?

Thank you for your time and for all the hard work put into improving
Javadoc.

Best regards, and always yours.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20250819/2a25e6dc/attachment.htm>