[9] RFR of 8069269: (spec) Defect in the System.nanoTime spec

[Martin Buchholz]

[+javadoc-dev]

On Fri, Jan 23, 2015 at 1:20 PM, Brian Burkhalter <
brian.burkhalter at oracle.com> wrote:

> On Jan 23, 2015, at 1:10 PM, Martin Buchholz <martinrb at 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>