[geometry] Documentation to inform user-facing decisions discoverable

[SeanCurtis-TRI]

Problem

There are, ultimately, design issues in the API that affect end users decisions. Many of these have been documented in the code. In some case, they've been included in the documentation for private or internal APIs. As such, the information is not discoverable through doxygen. This is part of a larger trend.

Examples:

• Drake camera not showing texture. #13179 Why isn't my obj textured in camera?
• hydroelastic: Links to SDFormat and URDF specification are broken? #14107 How do I specify properties (proximity, perception, illustration) in SDF/URDF files?
• from slack, MultibodyPlant doesn't document its default collision filtering behavior #13672 Collision filters are added to preclude contact between adjacent bodies? How should I have known that?
• Add parsing for reflected inertia parameters #14323 drake:foo custom SDF and URDF tags (reflected inertia parameters / bushing parameters / etc.) are documented, but only in internal namespace. (Note: dynamics-related parsing tags (as indicated here) have exactly the same problem, but this issue is tagged geometry and will be resolved when geometric documentation is resolved. The final solution can be adapted to dynamics as well.)
• Improve the documentation on resolution_hint #15743 (This will ultimately be part of a "Hydroelastic Contact User Guide".)

Solution

We need to scrub through the geometry code and distill the documentation into a better user guide. Through the use of tags and anchors, documentation for internal APIs can call back to that documentation so that it doesn't get duplicated.

Complexity

There are several issues that makes this harder than one might think at first. Taking parsing as an example:

• It makes sense that the function that does the parsing work should document what tags it is looking for and what it does if it finds/doesn't find them. That's simple function documentation. This serves the developer and its spatial locality increases the odds that it gets maintained along with the code (and will inform the user tests).
• The parsing code is internal so none of that good documentation gets put in rendered doxygen.
• Creating a standalone doxygen module is discoverable. It is also the ideal medium to put several disparate concepts into clear relationship. However, it is far removed from any implementation (see the first item in this point). This documentation serves the user by being discoverable and holistic.
• We don't really want to copy-and-paste the function documentation into the module documentation for all of the normal brittleness reasons.

So, the goal would be to document behavior once such that it serves both developer and user without introducing entropy (needlessly).

[DamrongGuoy]

Thank you for explanation. It took me a while to understand. It is indeed tricky to maintain the balance of users and developers.

[rpoyner-tri]

As a warmup, I searched for @anchor tags that are defined within a namespace internal block. Here are the results:

• sdf_contact_material

  • ref in multibody_plant.h

• urdf_contact_material

  • ref in multibody_plant.h

• point_contact_data_accessors

  • harmless; defined, never used.

• forward_dynamics_notation

  • harmless; defined, never used.

• internal_forward_dynamics

  • all refs are internal also, so harmless?

• abi_and_bias_force

  • all refs are internal also, so harmless?

• abi_computing_accelerations

  • all refs are internal also, so harmless?

• map_decision_variable_to_sdpa

  • all refs are internal also, so harmless?

So, the broken-link problems are covered by #14107. Next is to try to discover the full set of drake: extensions to SDF/URDF and their documentation.

[rpoyner-tri]

Here are all of the potential element/attribute names found, within
multibody/parsing.

• drake:acceleration

  • sdf element; urdf attribute
  • within joint/limit
  • not obviously documented anywhere?

• drake:accepting_renderer

  • sdf element where name is contents
  • urdf element where name is an attribute
  • within visual element
  • multiple instances allowed
  • documentation at detail_urdf_geometry.h and detail_scene_graph.h

• drake:linear_bushing_rpy

  • sdf, urdf element, assorted sub-parts
    • drake:bushing_force_damping
    • drake:bushing_force_stiffness
    • drake:bushing_frameA, drake:bushing_frameC
    • drake:bushing_torque_damping
    • drake:bushing_torque_stiffness
  • documented in detail_common.h

• drake:capsule

  • sdf: element, proposed for deprecation and removal sdformat: Should deprecate //geometry/drake:ellipsoid and //geometry/drake:capsule #14837
  • urdf: not parsed, proposed extension TODO in detail_urdf_geometry.cc
  • within geometry
  • contains sub-elements; maybe mimics spec descriptions?
  • not documented?

• drake:ellipsoid

  • sdf: element, proposed for deprecation and removal sdformat: Should deprecate //geometry/drake:ellipsoid and //geometry/drake:capsule #14837
    • contains sub-elements; maybe mimics spec descriptions?
  • urdf: element, a,b,c as float attributes
  • within geometry
  • not documented?

• drake:half_space

  • sdf: not used or parsed?
  • urdf: some examples, but not used or parsed?

• drake:collision_filter_group

  • element: equivalent layout in sdf, urdf, different idiomatic spellings
  • urdf: within robot
  • sdf: within model
  • various sub-parts
    • drake:ignored_collision_filter_group
    • drake:member
  • not documented?

• drake:declare_convex

  • sdf, urdf: empty element
  • within mesh
  • not documented?

• drake:diffuse_map

  • sdf: element, contents is a locator for a texture
  • within material
  • urdf: not parsed?
  • not documented

• drake:gear_ratio

  • sdf: element, float value in contents, within joint
  • urdf: element float value attribute, within transmission/actuator
  • not documented?

• drake:rotor_inertia

  • sdf: element, float value in contents, within joint
  • urdf: element float value attribute, within transmission/actuator
  • not documented?

• drake:joint

  • sdf, urdf element
  • assorted attributes and subelements
    • drake:child
    • drake:damping
    • drake:parent
  • not documented?

• drake:proximity_properties

  • sdf, urdf element
  • assorted sub-parts
    • drake:compliant_hydroelastic
    • drake:hunt_crossley_dissipation
    • drake:hydroelastic_modulus
    • drake:mesh_resolution_hint
    • drake:mu_dynamic
    • drake:mu_static
    • drake:point_contact_stiffness
    • drake:rigid_hydroelastic
  • within collision
  • documented here
    • multibody/parsing/detail_common.h
    • multibody/parsing/detail_scene_graph.h
    • multibody/parsing/detail_urdf_geometry.h

• drake:elastic_modulus

  • deprecated in favor of drake:hydroelastic_modulus

• drake:soft_hydroelastic

  • deprecated in favor of drake:compliant_hydroelastic

Summary: nothing is documented in any renderable place, much is undocumented. Several language definition questions need resolving.

[rpoyner-tri]

Boxes are checked. Of course it's not all perfect, but I think good enough to declare victory here. Closing.