DistrictResponsibles: extended documentation

entity/DistrictResponsible_entity/DistrictResponsible_entity.aod

@@ -178,6 +178,7 @@
     <entityParameter>
       <name>CollectedDistrictIds_param</name>
       <valueProcess>%aditoprj%/entity/DistrictResponsible_entity/entityfields/collecteddistrictids_param/valueProcess.js</valueProcess>
+      <documentation>%aditoprj%/entity/DistrictResponsible_entity/entityfields/collecteddistrictids_param/documentation.adoc</documentation>
     </entityParameter>
     <entityField>
       <name>MAIL</name>

entity/DistrictResponsible_entity/entityfields/collecteddistrictids_param/documentation.adoc

+Non exposed parameter that collects the districtIds for the given value of `OrgUid_param`.
+
+Advantages of encapsulation as a non exposed param:
+
+* one interface to other entities (e.g. the Organisation_entity)
+* logic for collecting districtIds is done within the `DistrictResponsible_entity` scope which means
+other entities don't have to collect the IDs themselfes. For example:
+The `Organisation_entity` doesn't have to collect the IDs because the `DistrictResponsible_entity` 
+_knows_ how to collect them.
+* the value of this `CollectedDistrictIds_param` can be passed to the `cacheKeyProcess` 
+(this enables us for example to cache district responsibles per Districtlist and not per Oranisation)
+* Calculation of the affected districtIds only when needed. For example: 
+The DistrictIds are not loaded when an Organisation is opened but when the 
+consumer data for the `DistrictResponsible_entity` is loaded 
+(=when the user changes the into the district responsibles tab)
\ No newline at end of file