<div dir="ltr"><p>Hello everyone,</p>
<p>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.</p>
<p>For instance, let’s compare the <code>StringBuilder</code> documentation in Java with its equivalent in C#:</p>
<ul>
<li>
<p>Java: <a rel="noopener" class="gmail-decorated-link" href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html">https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html<span aria-hidden="true" class="gmail-ms-0.5 gmail-inline-block gmail-align-middle gmail-leading-none"></span></a></p>
</li>
<li>
<p>C#: <a rel="noopener" class="gmail-decorated-link" href="https://learn.microsoft.com/es-es/dotnet/standard/base-types/stringbuilder">https://learn.microsoft.com/es-es/dotnet/standard/base-types/stringbuilder<span aria-hidden="true" class="gmail-ms-0.5 gmail-inline-block gmail-align-middle gmail-leading-none"></span></a></p>
</li>
</ul>
<p>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.</p>
<p>Similarly, if we look at Python’s documentation:</p>
<ul>
<li>
<p><a rel="noopener" class="gmail-decorated-link" href="https://www.pydocs.site/es/native-functions/string-methods/">https://www.pydocs.site/es/native-functions/string-methods/<span aria-hidden="true" class="gmail-ms-0.5 gmail-inline-block gmail-align-middle gmail-leading-none"></span></a></p>
</li>
</ul>
<p>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.</p>
<p>My question is:</p>
<ul>
<li>
<p>Is there any initiative to include more usage examples and concise, code-centric explanations in Javadoc?</p>
</li>
<li>
<p>Or, is there an alternative <em>official</em> documentation site that already follows this more example-driven approach?</p>
</li>
</ul>
<p>Thank you for your time and for all the hard work put into improving Javadoc.</p>
<p>Best regards, and always yours.</p></div>