In-line API documentation updates #152

Problem description
More explanations in the inline API documentation / description fields to clarify the API

Expected action

• Add terminology items in the info.description field content (see proposal below)
• Reorganizing the text order and adding some details found only lateron deep inside the API definition.
• Clarify the integer result of the API call is not clear: is it
  • the number of people in the Area (average across all cells)
  • the number of people in each cell of the area
  • the number of people per square kilometer (not possible as the result is just an integer)
  • the number of people in a given area divided by the size of that area (??)
  • align all description to the same interpretation across the yaml file
• for polygons:
  • the calculation of grid cell (equal-sized ?) sizes is not clear. how is a polygon divided into "equal-sized cells" ?
  • "polygon calculated with geohash precisions ??": Are the geo-coordinates mapped to geohashes with default level 7 ? how is the provided precision level used ? does it replace the default (7) ?
  • what if the precision level (e.g. 12) results in cells smaller than a square kilometer ?
• "exact interpretation of minimum and maximum depends on the API Provider's underlying estimation algorithm." - this is not very clear. At least one (expected) interpretation should be given.

Then apply terms consistently across all definitions.

Additional context
As this is going for a stable 1.0.0 release, extra attention to the API documentation is needed.

Proposed terminology update
Attached is a proposal for updates of the info.description field (done with Copilot and my own updates). Feel free tu use as you see fit. See #152 (comment) below.