some work on the doc

[gares]

No description provided.

[gares]

@CohenCyril I've some troubles understanding this lat bullet point, see also the change below

[CohenCyril]

Suggested change

	(* not sure I get this use case *)
	HB.instance Definition _ := StructureName.Build T cT.
	(* cloning a structure *)
	HB.instance Definition _ := StructureName.Build T' (StructureName.of T).
	(* cloning a structure *)
	HB.instance Definition _ := StructureName.Build T cT.

I see why you are confused. Build does not have the same type as for factories and mixins.

Indeed we since the only authorized way of making a class is to get it from another structure
StructureName.Build T' (StructureName.of T). would be redundant, that's way I skip StructureName.of altogether and the second argument of StructureName.Build is simply another structure we want to take the class from.

[CohenCyril]

Maybe it should have another name. Maybe we should even redefine clone to be this one...

[CohenCyril]

I liked the fact that it's a Build because T comes first and then "how to build" is simply different by nature for classes.

[gares]

The example does not show how you get cT, so I'm not so sure I can fix the comment myself.
It is not just the code snippet, it is also the bullet point which fails to parse to me.

[gares]

- [StructureName.Build T cT : StructureName T] outputs the class of the canonical,
    and [StructureName.type] of [cT], and give it the type [Structure]. So that it is
    ready to use in combination with HB.instance, as in

[gares]

S.Build T cT builds a class record. It is projected out the canonical S on T. [Structure] seem unbound.

[CohenCyril]

It should read:

- [StructureName.Build T cT] outputs the class of the canonical [StructureName.type] of [cT],
  and gives it the type [StructureName T]. So that it is ready to use in combination with HB.instance, as in

[gares]

Can you clarify the naming convention? This is my understanding

• T is a type (a carrier)
• sT is a structure on T (T is the carrier)
• cT is the class of sT

but I guess it is wrong

[CohenCyril]

Can you clarify the naming convention? This is my understanding

• T is a type (a carrier)
• sT is a structure on T (T is the carrier)
• cT is the class of sT

but I guess it is wrong

Right, I should use T' then in the problematic bullet. I used cT to mean "Type with a canonical", but that's not intuitive at all.

[gares]

Maybe I should have opened an issue instead of a PR, and let you open the PR.
Maybe this is what we should do, you update the doc and I do the crash test dummy.

[gares]

Great!