Summary

Massively improve the documentation of java.lang.classfile.constantpool package.

Problem

The java.lang.classfile.constantpool package is shipped with bare documentation. Additional documentation may help users to better understand the API model, the constant pool, and best practices.

Solution

1. Improve the package info to give an overview about the usage of pool entries in reading and writing, pool builders (including temporary pools) and the exception behaviors.
2. For each pool entry, describe its conceptual/physical data model: this will be removed from the java.lang.classfile top level documentation later.
3. Add notes to indicate how to get a symbolic representation, to discourage the use of raw constant pool entries.

Specification

See the attachments. Note that the latest revisions javadoc and apidiff are available in CR links.