Hi. I’m looking at the documentation metadata on UsdObject relation to this function: Universal Scene Description: UsdObject Class Reference. I’ve seen it used to document the prims and properties in schema.usda files. Is this metadata reserved only for that purpose or is also appropriate for runtime end-user documentation of an asset? Any other useful cases that we can add to the API docs? Thanks!
Hi Matias! Currently the documentation metadata field is initially set from the schema.usda as you mention. It can, however, be used for “scene documentation” authored by users through the UsdObject APIs.
We’re currently working on making this more distinct, so that the documentation field is solely for scene documentation for end-users, and new additional metadata will be added to have “brief doc”, authored in schema.usda, and accessed by UsdPrimDefinition. This “brief doc” will be similar to the API doc currently in schema.usda, but authored as reference doc for users of the schema classes.
2 Likes
Thanks Dan! That helps. Would you like a contribution to add more explanation to UsdObject.GetDocumentation() or will that be covered in the “brief doc” update?
We’ll likely be updating the docs for UsdObject.GetDocumentation() based on the change, but any contributions you wanted to add are welcome.
@dsyu With this change, is there a preferred way to query an attribute’s brief doc (for example, to surface a schema documentation as a tooltip)?
If the attribute is defined in a typed schema, currently the most straight-forward approach is to use GetPropertyDocumentation() on the prim’s primDef (retreived via GetPrimDefinition()). If the attribute is coming from an API schema, you’d need to get the list of applied schemas and look each one up in the schema registry. We’re planning on adding APIs (e.g., “GetUserDocumentationBrief()”) to retrieve the brief user doc(s) for prims and properties.