Document diverging from the spec with plural "s" naming scheme

[s-heppner]

Currently, our module docstrings do not explain that we diverge from the spec when naming aggregations. I suggest adding something like this to the module docstrings:

It is common in UML to use singular form for aggregations, which is the case for the meta-model. This is, however, in contrast to programming code, where plural form for sequences is common. Since the naming of XML elements has direct influence on the programming code, we name the properties in plural form diverging from the name in the meta-model. For example, submodelElements instead of submodelElement in case of Submodel/submodelElement property in the meta-model.

In cases where plural form made no sense for a property, we kept it as-is in singular form (e.g., is_case_of). The full list of exceptions is available as code in aas-core-meta.

[mristin]

Sounds good to me!

Mind the last sentence:

The full list of exceptions is available as code in aas-core-meta.

It doesn't make sense in the docstring as-is.

[s-heppner]

Fair enough. How about this?

The full list of exceptions is available in the test files as variable: hard_wired_plural_exceptions.

[mristin]

Can we have a quick call about this? The docstring is used for multiple purposes. For example, it is showed in HTML documentation, but also included as documentation in SDKs.

It does not really make sense to include why we use a different naming convention from the book as long as the generated files conform to the spec. We follow the conventions across the programming languages and schemas, but this is very obvious.

In the end, I would turn the explanation around: explain why the book is so weird for people coming from the software engineering side (singular instead of plural).

Here's my try:

The official specification in the book form uses UML to express the meta-model. 
Following UML naming convention, the book uses singular form for many of
the attributes even though they refer to aggregations. Since this is very unusual 
outside of the UML, we write aggregation attributes in plural form (*e.g.*, 
:attr:`Reference.keys`). Where the attribute names made no sense in plural, we stick
to the name as-is (*e.g.*, :attr:`Concept_description.is_case_of`).

Linking to the test data is misleading in the case of SDKs -- the SDKs do not have that test data, it's the test data of aas-core-meta.

In addition, we have to use the references so that we get errors if the attributes are removed from the meta-model. Otherwise, the mistakes will slip any very quickly.

[s-heppner]

I was hoping to reuse the text across the several versions, but you're right, it's best to link them directly in each version.

[mristin]

(cross-posting, please see my updated comment above)