RFR: JDK-8272944: Use snippets in jdk.javadoc documentation

[Jonathan Gibbons]

Please review a patch to convert an example in the `jdk.javadoc` documentation to use snippets instead of raw HTML and/or `{@code }`.  There are some minor tweaks to the text of the example, but no changes to the normative specification of the package.

Given that the example is in `package-info.java`, a minor change is required in `JavacElements` to ensure that the package symbol is completed (i.e. the `package-info.java` file has been read) when accessing the `PackageElement`.

-------------

Commit messages:
 - JDK-8272944: Use snippets in jdk.javadoc documentation

Changes: https://git.openjdk.java.net/jdk/pull/6685/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=6685&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8272944
  Stats: 146 lines in 2 files changed: 33 ins; 0 del; 113 mod
  Patch: https://git.openjdk.java.net/jdk/pull/6685.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/6685/head:pull/6685

PR: https://git.openjdk.java.net/jdk/pull/6685