RFR: 8248877: Document API contract for MetaspaceObj subtypes

[Coleen Phillimore]

On Thu, 3 Jun 2021 00:36:56 GMT, Ioi Lam <iklam at openjdk.org> wrote:

> This PR adds documentation for the (non-virtual) functions that subtypes of MetaspaceObj are required to implement in order for certain templates to work properly. 
> 
> Requested by @rose00 (sorry I took a long time ....).

Looks good with some minor suggestions.

src/hotspot/share/memory/allocation.hpp line 277:

> 275:   //
> 276:   // The following functions are required by MetadataFactory::free_metadata():
> 277:   //   bool on_stack() { return false; } // DEBUG only

I don't think the // DEBUG only comment is correct.  on_stack is used in product mode.  Can you remove this?

src/hotspot/share/memory/allocation.hpp line 283:

> 281:   // Elsewhere in the hierarchy of MetaspaceObj, type() and/or size() can be static
> 282:   // if constant.
> 283: 

maybe move this up to be under 275 because it talks about those.

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

Marked as reviewed by coleenp (Reviewer).

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