RFC: 8247976: Update HotSpot Style Guide for C++14 adoption

[Kim Barrett]

> On Jul 11, 2020, at 10:56 AM, Kim Barrett <kim.barrett at oracle.com> wrote:
> 
>> On Jun 23, 2020, at 3:32 PM, Kim Barrett <kim.barrett at oracle.com> wrote:
>> 
>> Please review / comment on this proposed update to the HotSpot Style
>> Guide. This is part of the work for JDK-8208089: JEP 347: Adopt C++14
>> Language Features in the JDK.
>> 
>> […]  Once
>> reviewed, the finished text can be used to update the wiki, unless we
>> decide it should be homed somewhere else.
> 
> There has recently been a lot of discussion about where this and
> somewhat similar documents should reside.  Most of that has been about
> a Java Style Guide, which has somewhat different issues than this one.
> (The HotSpot Style Guide is very focused in scope, and is unlikely to
> have much, if any, influence on usage by the wider C++ community.)
> 
> Proposed homes include:
> 
> - Remain in the OpenJDK wiki.
> - Use an informational JEP.
> - Move to the new Developer's Guide.
> - Move to the JDK repository.
> 
> For some of the discussion, see comments in JDK-8208089, as well as
> the recent thread on the jdk-dev mailing list:
> https://mail.openjdk.java.net/pipermail/jdk-dev/2020-June/004443.html
> https://mail.openjdk.java.net/pipermail/jdk-dev/2020-July/004461.html
> 
> Based on that discussion, I'm planning to move it to the JDK
> repository, in jdk/jdk/doc. That is already a place for
> developer-focused documentation; it's the home of building.{md,html},
> testing.{md,html}, and ide.{md,html}. I think this style guide fits
> well with that collection.
> 
> I think the other two wiki pages associated with the current wiki
> HotSpot Style Guide would similarly fit well there, and I suggest we
> move them as well.
> 
> Comments?

I made a few formatting tweaks to account for using the approved
markdown processor (pandoc, via make update-build-docs); I'd been
using a different processor, and noticed some problems with the
generated html when I switched to using pandoc.

I've also moved the files to jdk/jdk/doc.

Reducing the heading "depths" made pandoc generate a nice TOC at the beginning.

I removed the "===" separators, because pandoc wasn't producing a
horizontal line separator for them, unlike the previous (extended)
processor.

There were some naked URLs that needed to be surrounded by <> to be
autolinked by pandoc, unlike the previous (extended) processor.

New webrev:
full: https://cr.openjdk.java.net/~kbarrett/8247976/hotspot-style.03/
incr: https://cr.openjdk.java.net/~kbarrett/8247976/hotspot-style.03.inc/

The diffs for the incremental .html aren't particularly interesting,
since different markdown processors were used to generate them.

I'm intending to leave the move of the other two related wiki pages to later.

Hopefully this is the last of this round of edits, though I'm
expecting there will soon be a number of requests for further changes
from this "baseline".