Review of documentation output and UML

[FlavioRizzolo]

The documentation and UML models proved to be very useful in design and architecture discussions where digging thru XSDs is not practical. In the process I found a few issues:

• Quite a few cardinalities seem to be wrong in the documentation page, whereas they seem fine in the UML. For instance, in PhysicalStructureGroup, PhysicalStructureReference[PhysicalStructure] is 0..1 when it should be 0..*. Same with the self-reference PhysicalStructureGroupReference[PhysicalStructureGroup]. I noticed that happens in other groups as well, e.g. VariableGroup and PhysicalInstanceGroup.

• Shouldn't a PhysicalInstance have only one PhysicalStructure? I thought the UML cardinalities were right before, but in this case the documentation in the page seems to be right and the UML wrong. I'm not sure which cardinality to trust now.

• There are also some associations missing in the UML. For instance, VariableReference[Variable] in VariableScheme, RepresentedVariableReference[RepresentedVariable] in Variable, and ConceptualVariableReference[ConceptualVariable] in RepresentedVariable. I can't tell the reason why some associations appear and some others don't, given that the Sphinx diagrams I checked seemed to be correct.

• The Sphinx diagrams seem to have a weird way of representing self-references. Take VariableScheme, for instance: there is a VariableSchemeReference loop on the Properties box that doesn't make much sense to me, especially when there is a separate association to a VariableScheme oval as well. Why the loop in that unusual place? The same happens in all classes with self-references I checked, e.g. Variable, VariableGroup, PhysicalInstanceGroup, PhysicalStructureGroup. If there is any reason for that, it's not at all obvious.

[spuddybike]

review again once DDItoCogs work has completed

[spuddybike]

moved to documentation pages

[spuddybike]

Sphinx documentation issue covered in https://github.com/ddialliance/DDI-Lifecycle-Technical-Guide/issues/1

[DanSmith]

Thanks for the feedback, this is addressed in https://github.com/Colectica/cogs/commit/3aa72e70bd47aed8c651974bb0ddfa52b33ef802