Document API contract for MetaspaceObj subtypes

(Per John Rose)

To support MetspaceClosure, all subtypes of of the C++ class MetaspaceObj must define size(), type() and metaspace_pointers_do(). For subtypes under MetaData, these are dispatched via a vtable. However, for other subtypes that have no vtables (such as ConstMethod), these are dispatched via the templates in MetspaceClosure.

Similarly, on_stack() and deallocate() are required by the template function MetadataFactory::free_metadata().

This API contract is currently not documented by MetaspaceObj. This is a documentation bug. If we had "concepts" in C++, MetaspaceObj should have an associated concept which various templates would refer to, as providing constraints on their arguments. (Kind of likes a generic bound in Java.)

Something like:

class MetaspaceObj {
  // This class has no virtual functions (although Metadata does,
  // below it). Nevertheless, there are some protocols that all
  // subtypes of MetaspaceObj are expected to implement, so that
  // templates which are defined for this class hierarchy can
  // work uniformly. They are as follows:
  //
  // void metaspace_pointers_do(MetaspaceClosure* it) { <walk my refs> }
  // int size() const { return align_up(sizeof(<This>), wordSize) / wordSize; }
  // MetaspaceObj::Type type() const { return <This>Type; }
  // DEBUG_ONLY(bool on_stack() { return false; })
  // void deallocate_contents(ClassLoaderData* loader_data);
  //
  // Within the sub-hierarchy of Metadata, these are virtuals.
  // Elsewhere in the hierarchy of MetaspaceObj, type and/or size can be static if constant.