Enriching the Javadoc with more content from the guides

[devguyio]

Hi folks,
I'm a big fan of Javadoc that contains rich, conceptual documentation which I can read directly from the IDE. E.g. the java.util.stream package javadoc .

While I was getting started with Quarkus & Vert.x, the rabbit hole lead me to Mutiny, which means I didn't come first to the website and Mutiny docs, I checked the Javadoc of Uni, Multi and was clueless.

Going through the amazing Mutiny guides made me wonder if you've considered before enriching the Javadoc with content from the guides? This would be hugely beneficial for folks who get introduced to Mutiny through Quarkus & Vert.x.

[jponge]

Javadoc shall contain just the technical documentation for an API, no less, no more. The Javadoc format isn't enjoyable to write either, for instance, we need to escape certain symbols such as > / <, embedding images is so-so, etc.

There's always room for improving javadocs (aka API docs). Still, the guides are different: they explain the philosophy, they show some guided exploration of the APIs, show some common usages, etc.