Doxygen \ref is removed from documentation fields in generatedSchema.usda

[nvmkuruc]

Description of Issue

Attribute doc strings in schema.usda may include doxygen commands like this

OpenUSD/pxr/usd/usdGeom/schema.usda

Line 2326 in 59992d2

\\ref UsdGeom_CameraUnits .""")

However, when usdGenSchema is run, the \\ref is removed, leaving the doc string for the schema definition incomplete.

OpenUSD/pxr/usd/usdGeom/generatedSchema.usda

Line 4210 in 59992d2

."""

Steps to Reproduce

System Information (OS, Hardware)

Package Versions

Build Flags

[jesschimein]

Filed as internal issue #USD-10164

[spiffmon]

Good opportunity to say... we anticipate all of the doxygen/developer documentation to be eliminated from the SchemaRegistry in favor of userDoc/userDocBrief, in time. Since solving this problem in a nice way in all cases is, in our opinion, tricky, and since nobody (before now :-) ) has noticed, we'd like to close this as "not fixing"

[nvmkuruc]

we anticipate all of the doxygen/developer documentation to be eliminated from the SchemaRegistry in favor of userDoc/userDocBrief, in time

This was going to be our recommendation--

Since solving this problem in a nice way in all cases is, in our opinion, trick

-- for this exact reason.

Do you have a timeline or way for us to track the status of the userDoc / userDocBrief effort?

[spiffmon]

We're working on it - stay tuned, please!

[nvmkuruc]

Hi @spiffmon and @dsyu-pixar. Now that OpenUSD supports userDocBrief would you accept a brief documentation update for the Camera schema for 25.05 or are you already working on this?

Thanks!

[dsyu-pixar]

@nvmkuruc we're initially focusing on UsdLux schemas (followed by UsdRender and possibly UsdShade), so we'd welcome updates for Camera and any other UsdGeom schemas (thank you!). Let me know if you run into any issues with userDoc/userDocBrief, or if any of the basic steps in the "Generating Schema User Docs" section of docs/README.md don't make sense.

[nvmkuruc]

Thanks Dan!