"doc" metadata field removal for schemas?

Community USD
1

Hello!

I’m looking into removing the “doc” API documentation metadata from the schema registry. I’m hoping to get some feedback on how this will impact folks, especially tools devs.

Historically the "doc’ metadata field in schemas was intended to be “API documentation” (often formatted using doxygen directives) and gets added to generated C++ code for non-codeless schemas, and then used to generate API documentation for USD via doxygen. Currently USD also propagates this content into the schema registry and makes it available via UsdPrimDefinition::GetDocumentation() / GetPropertyDocumentation().

In release 24.08, we added a new process for authoring “user doc” for schemas. This process uses new custom metadata fields (“userDoc” and “userDocBrief”) for schema classes and properties. “userDocBrief” now gets propagated to the schema registry and can be retrieved using UsdPrimDefinition::GetDocumentation() / GetPropertyDocumentation(). The “userDocBrief” field typically contains a short 1 or 2 sentence description of the schema class or property for users, which can be displayed to users in a DCC tool, or other user-facing context.

With the addition of “userDocBrief”, the “doc” metadata field is no longer needed in the schema registry, hence my plan to remove it (and maybe get some modest performance gains in schema registry initialization). However, currently, only the usdVol schemas have actual “userDocBrief” content authored, which means that until we have userDocBrief content for all schema classes and properties, many schemas will return nothing for calls to UsdPrimDefinition::GetDocumentation / GetPropertyDocumentation.

Additionally, UsdObject::GetDocumentation() for prims and properties currently accesses the “doc” metadata field. This change will make this call also return nothing for prims/properties from schemas.

I’m curious to know if anyone is relying on either the primdef / object GetDocumentation APIs or the “doc” metadata field in general for their USD use cases.

2

I thought you outlined a really good plan here: The purpose of UsdObject's Documentation metadata - #2 by dsyu

Sounds like the plan has changed since then? How come?

I think a generalized doc metadata to provide asset-specific documentation seems useful. I would personally prefer to see:

  1. doc and GetDocumentation() to be empty by default and repurposed to serve as asset-specific documentation.
  2. To have a new API for userDoc and userDocBrief.

Also schemaDoc makes more sense in my mind than userDoc for that purpose.

Just my two cents on it. I don’t think we have anything built on this right now, but these were considerations I was making for future ASWF Assets WG contributions.

2 Likes
3

Thanks Matias, I appreciate the feedback!

The plan (so to speak) is at least partly in-line with what I mentioned before, with the goal of separating “API doc” from user doc by adding a new metadata field for user doc. The existing GetDocumentation/SetDocumentation APIs on UsdObject will continue to work with the “doc” metadata field and thereby still usable for user-editable asset-specific documentation.

For PrimDef’s (not UsdObject’s) GetDocumentation we’ve switched things to use the “userDocBrief” content rather than the API “doc” content we were using before. This GetDocumentation was not ever intended to be used for asset-specific doc (and is authored by the schema dev) so changing this API to something like “GetUserDocumentation” would be unnecessary, in my opinion?

1 Like
4

I see now. The last paragraph had thrown me off. Thanks for clarifying. Yes, that sounds reasonable to me.

1 Like