[+javadoc-dev]
On Fri, Jan 23, 2015 at 1:20 PM, Brian Burkhalter <
brian.burkhal...@oracle.com> wrote:
> On Jan 23, 2015, at 1:10 PM, Martin Buchholz <marti...@google.com> wrote:
>
> We have struggled for years with formatting for code samples. If you want
> to change it, get authoritative statement on how to do it with latest
> javadoc, publish it somewhere, and change it everywhere. Putting the
> }</pre> on a line by itself did not produce the most readable output IIRC.
>
>
> Any official guidance here would be welcome. I actually investigated the
> formatting style in other classes, e.g., AsynchronousServerSocketChannel,
> ServiceLoader, etc., and there is in fact a lack of consistency aside from
> the use of <pre></pre>. I did however build the docs before and after this
> change and the revised one looks better, at least on my system.
>
Here's my view of the history. javadoc does not provide a baked in
{@codesnippet ...} (PLEEEASE javadoc maintainers, add it!) so people have
come up with different local styles combining {@code and <pre>. But
javadoc's output changes every release, so people have changed their
blessed style based on both personal preference and the target version of
javadoc used to generate their docs. In java.util.concurrent, we've
currently standardized on
* <pre> {@code
...
* }}</pre>
