Document design of DOM objects

[scpeters]

Several questions about the design of libsdformat's DOM objects have come up in discussions with @EricCousineau-TRI over time, including the following:

• Lifetime of DOM elements, lifetime or relationship
• role of semantics, why not just use xsd to generate structs
• How dynamic is the DOM? If you call SetPoseRelativeTo, does that modify the embedded ElementPtr? the PoseRelativeToGraph?
• Is the DOM a read-only interface to a model parsed from XML? Or would you construct a model programmatically from DOM objects?

[EricCousineau-TRI]

Ideal target is SDFormat 1.8 release (Target: December 1, 2020)

[EricCousineau-TRI]

Relates #312 - on error behavior of XML parsing, should return Error.
But for public DOM API, not sure if mutators should either return Error, or throw exceptions.

[chapulina]

Is the DOM a read-only interface to a model parsed from XML? Or would you construct a model programmatically from DOM objects?

We're close to December 1st 😄 Do we have an answer to this question?

I'm asking in the context of #388. We use SDF DOM classes to store data inside ign-gazebo, and convert that to and from protobuf messages. So I need a way to construct a sdf::Heightmap from an ignition::msgs::HeightmapGeom.

[scpeters]

there have been a few recent changes (such as #772) that imply some answers to the questions about the DOM object design, though we haven't formally documented answers to these questions yet

[scpeters]

• Is the DOM a read-only interface to a model parsed from XML? Or would you construct a model programmatically from DOM objects?

Recent pull requests (such as #785, #838, #839, #840, #841) provide functionality to construct models, links, etc from DOM objects rather than editing XML strings, which would imply that the DOM is not simply a read-only interface.

[scpeters]

• How dynamic is the DOM? If you call SetPoseRelativeTo, does that modify the embedded ElementPtr? the PoseRelativeToGraph?

The Frame Semantics graphs are currently not updated by DOM API calls. It would be good to find a way to keep them in sync or decouple them in some way.