Docs: define extension rules

[stevedh]

It would be helpful to document the intended behavior of the "extends", "is_base", and "points_base" fields of equipment so we can use them correctly. From the data, it seems like:

• If an entity "extends" another entity, the type (list of markers, references, and optinoal references) should be made up of the ones specified in the leaf entity, as well as these fields on equipment read by following "extends" fields.
• If a piece of equipment "extends" another one, you should be able to follow the list of "extends" equipment until you reach one where "is_base=True"
• The points and functions list of a piece of equipment contains the union of all pieces of equipment it extends.
• What is points_base for?

[jasonpohl-bIOT]

Sorry for the delay on this, will get this updated in the docs and share and be more active in the repo in 2024.

[annieDehghani]

@stevedh We will update the docs to reflect this, but in answer to your questions:

If an entity "extends" another entity, the type (list of markers, references, and optional references) should be made up of the ones specified in the leaf entity, as well as these fields on equipment read by following "extends" fields.

Answer: Correct

If a piece of equipment "extends" another one, you should be able to follow the list of "extends" equipment until you reach one where "is_base=True"

Answer: In general yes, although there are exceptions. In general the is_base flag is a grouping mechanism concept.

The points and functions list of a piece of equipment contains the union of all pieces of equipment it extends.
What is points_base for?

Points and functions are not automatically inherited by extended equip types nor are they inherited up the chain by parent types. By specifying points as points_base, they are then applied to the base type and inherited by the child equip types.