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.
