document ThirdParty type and categories [ci-skip]

src/Bundle/ChillThirdPartyBundle/Entity/ThirdParty.php

@@ -45,6 +45,40 @@ use function spl_object_hash;
  * all users with the right 'CHILL_3PARTY_3PARTY_SEE', 'CHILL_3PARTY_3 to see, select and edit parties for this
  * center.
  *
+ * A ThirdParty may have:
+ *
+ * * 0, one or more categories;
+ * * 0, one or more type
+ * * 1 kind.
+ *
+ * ## Kind
+ *
+ * The kind indicate if a thirdparty is a:
+ *
+ * * company ("personne morale");
+ * * a contact ("personne morale")
+ * * a child inside a company ("contact" in French). Only companies may have childs
+ *
+ * **take care** the french translation may lead to misinterpretation, as the string "contact" is the translation of
+ * kind "child".
+ *
+ * ## Categories and types
+ *
+ * ThirdParty may have zero, one or more categories and/or type.
+ *
+ * Categories are managed in the database. The Chill administrator may create or desactivate categories.
+ *
+ * Types are also a way to categorize the thirdparties, but this is done **into the code**, through
+ * @link{Chill\ThirdPartyBundle\ThirdPartyType\ThirdPartyTypeProviderInterface}. The type is stored into the
+ * database by a Php array, mapped by a jsonb into the database. This has one advantage: it is easily searchable.
+ *
+ * As the list of type is hardcoded into database, it is more easily searchable. (for chill 2.0, the
+ * @link{Chill\ThirdPartyBundle\Form\Type\PickThirdPartyDynamicType} does not support it yet, but
+ * the legacy @link{Chill\ThirdPartyBundle\Form\Type\PickThirdPartyType} does.
+ *
+ * The difference between categories and types is transparent for user: they choose the same fields into the UI, without
+ * noticing a difference.
+ *
  * @ORM\Entity
  * @ORM\Table(name="chill_3party.third_party")
  * @DiscriminatorMap(typeProperty="type", mapping={