docs: update inline API documentation, rename schemas and align terminology

[albertoramosmonagas]

What type of PR is this?

Add one of the following kinds:

• documentation

What this PR does / why we need it:

Updates the info.description field with expanded terminology and clarified definitions per release management review. Renames schemas (Area->GeoArea, AreaType->GeoAreaType, Polygon->GeoPolygon, ResponseStatus->ResponseQualityInfo) to avoid collision with CAMARA common datatypes. Removes all people/km2 references, deduplicates repeated sections, fixes non-ASCII characters, and aligns terminology (API Consumer, OperationId vs x-correlator).

Which issue(s) this PR fixes:

Fixes #152, #154

Special notes for reviewers:

Population Density is now defined as "Estimated number of people in a grid cell during a one-hour time slot, expressed as an integer value." All people/km2 references have been removed from the file, including schema field descriptions (pplDensity, maxPplDensity, minPplDensity) and the DensityEstimation schema description.

The ResponseQualityInfo rename aligns with the equivalent change proposed in Predictive Connectivity Data (issue camaraproject/PredictiveConnectivityData#86). ResponseQualityInfo was preferred over DataQualityInfo because the response can include non-data values such as OPERATION_NOT_COMPLETED.

Changelog input

 release-note
Updated info.description with expanded terminology definitions, reorganized API documentation structure, renamed Area/AreaType/Polygon to GeoArea/GeoAreaType/GeoPolygon, renamed ResponseStatus to ResponseQualityInfo, and aligned all field descriptions for consistency.

[albertoramosmonagas]

Hi @tanjadegroot, some changes applied to the current txt.

1. Density. The Introduction and the definition of Population Density no longer refer to “per square kilometer.” It is now defined as the estimated number of people per cell and per hour, consistently with the pplDensity fields.

2. Polygon grid (in Grid Cell and Precision → POLYGON). It now refers to the geohash cells covering the polygon, rather than converting the polygon vertices into geohashes. Level 7 is now shown only as the default value, and indicative cell sizes have been added.

3. Geohash.

   • Replaced third-party website references with a Wikipedia link.
   • Level 12 is now described as the “maximum supported by this API.”
   • Corrected the Spain example to use "e".

4. Polygon outside the supported area. The response is now status: AREA_NOT_SUPPORTED instead of an “empty array.”

5. Geohash list.

   • Restored the requirement that POLYGON must be supported by all MNOs.
   • Restored the UNSUPPORTED_AREA_TYPE error.

6. 422 errors. Added the complete error codes, including the POPULATION_DENSITY_DATA. prefix.

7. PRIVATE_KEY_JWT. Restored the original wording (“would be repeated”), which no longer contradicts the previous sentence.

8. Callback. Replaced “should” with “RECOMMENDED,” consistently with the other section describing callback behavior.

9. Restored links. Re-added the references to k-anonymity and Identity and Consent Management in the authentication section.

[jgarciahospital]

LGTM

[tanjadegroot]

@albertoramosmonagas Many thanks for the update !! I included a few comments.

[albertoramosmonagas]

Hi @tanjadegroot, I think everything from the release management review has already been implemented.

[tanjadegroot]

looks good ! Thanks @albertoramosmonagas