chore(Crs): update and refine documentation

src/Core/Geographic/Crs.ts

@@ -5,7 +5,9 @@ import type { ProjectionDefinition } from 'proj4';
 proj4.defs('EPSG:4978', '+proj=geocent +datum=WGS84 +units=m +no_defs');
 
 /**
- * A projection as a CRS identifier string.
+ * A projection as a CRS identifier string. This identifier references a
+ * projection definition previously defined with
+ * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections).
  */
 export type ProjectionLike = string;
 
@@ -19,49 +21,76 @@ function mustBeString(crs: string) {
     }
 }
 
+/**
+ * Checks that a given CRS identifier follows the TMS:XXXX format.
+ * @internal
+ *
+ * @param crs - The CRS identifier string.
+ */
 export function isTms(crs: string) {
     return isString(crs) && crs.startsWith('TMS');
 }
 
+/**
+ * Checks that a given CRS identifier follows the EPSG:XXXX format.
+ * @internal
+ *
+ * @param crs - The CRS identifier string.
+ */
 export function isEpsg(crs: string) {
     return isString(crs) && crs.startsWith('EPSG');
 }
 
 /**
- * Format crs to tile matrix set notation: TMS:XXXX.
+ * Converts the input to the tile matrix set notation: TMS:XXXX.
+ * @internal
  *
- * @param crs - The crs to format
- * @returns formated crs
+ * @param crs - The input to format.
  */
 export function formatToTms(crs: string) {
     mustBeString(crs);
     return isTms(crs) ? crs : `TMS:${crs.match(/\d+/)?.[0]}`;
 }
 
 /**
- * Format crs to European Petroleum Survey Group notation: EPSG:XXXX.
+ * Converts the input to European Petroleum Survey Group notation: EPSG:XXXX.
+ * @internal
  *
- * @param crs - The crs to format
- * @returns formated crs
+ * @param crs - The input to format.
  */
 export function formatToEPSG(crs: string) {
     mustBeString(crs);
     return isEpsg(crs) ? crs : `EPSG:${crs.match(/\d+/)?.[0]}`;
 }
 
 /**
- * Units that can be used for a CRS.
+ * System units supported for a coordinate system. See
+ * [proj](https://proj4.org/en/9.5/operations/conversions/unitconvert.html#angular-units).
+ * Note that only degree and meters units are supported for now.
  */
 export const UNIT = {
+    /**
+     * Angular unit in degree.
+     */
     DEGREE: 1,
+    /**
+     * Distance unit in meter.
+     */
     METER: 2,
 } as const;
 
+/**
+ * @internal
+ */
 export const tms_3857 = 'TMS:3857';
+/**
+ * @internal
+ */
 export const tms_4326 = 'TMS:4326';
 
 /**
- * Is the CRS EPSG:4326?
+ * Checks that the CRS is EPSG:4326.
+ * @internal
  *
  * @param crs - The CRS to test.
  */
@@ -84,9 +113,9 @@ function unitFromProj4Unit(proj: ProjectionDefinition) {
 }
 
 /**
- * Get the unit to use with the CRS.
+ * Returns the horizontal coordinates system units associated with this CRS.
  *
- * @param crs - The CRS to get the unit from.
+ * @param crs - The CRS to extract the unit from.
  * @returns Either `UNIT.METER`, `UNIT.DEGREE` or `undefined`.
  */
 export function toUnit(crs: ProjectionLike) {
@@ -99,30 +128,30 @@ export function toUnit(crs: ProjectionLike) {
 }
 
 /**
- * Assert that the CRS is using metric units.
+ * Asserts that the CRS is using metric units.
  *
- * @param crs - The CRS to validate.
+ * @param crs - The CRS to check.
  * @throws {@link Error} if the CRS is not valid.
  */
 export function isMetricUnit(crs: ProjectionLike) {
     return (toUnit(crs) == UNIT.METER);
 }
 
 /**
- * Assert that the CRS is geographic.
+ * Asserts that the CRS is geographic.
  *
- * @param crs - The CRS to validate.
+ * @param crs - The CRS to check.
  * @throws {@link Error} if the CRS is not valid.
  */
 export function isGeographic(crs: ProjectionLike) {
     return (toUnit(crs) == UNIT.DEGREE);
 }
 
 /**
- * Is the CRS geocentric?
- * if crs isn't defined the method returns false.
+ * Asserts that the CRS is geocentric.
  *
  * @param crs - The CRS to test.
+ * @returns false if the crs isn't defined.
  */
 export function isGeocentric(crs: ProjectionLike) {
     mustBeString(crs);
@@ -131,11 +160,11 @@ export function isGeocentric(crs: ProjectionLike) {
 }
 
 /**
- * Assert that the CRS is a valid one.
+ * Asserts that the CRS is valid, meaning it has been previously defined and
+ * includes an unit.
  *
- * @param crs - The CRS to validate.
- *
- * @throws {@link Error} if the CRS is not valid.
+ * @param crs - The CRS to test.
+ * @throws {@link Error} if the crs is not valid.
  */
 export function isValid(crs: ProjectionLike) {
     const proj = proj4.defs(crs);
@@ -148,7 +177,7 @@ export function isValid(crs: ProjectionLike) {
 }
 
 /**
- * Give a reasonnable epsilon to use with this CRS.
+ * Gives a reasonnable epsilon for this CRS.
  *
  * @param crs - The CRS to use.
  * @returns 0.01 if the CRS is EPSG:4326, 0.001 otherwise.
@@ -162,10 +191,12 @@ export function reasonnableEpsilon(crs: ProjectionLike) {
 }
 
 /**
- * Define a proj4 projection as a string and reference.
+ * Defines a proj4 projection as a named alias.
+ * This function is a specialized wrapper over the
+ * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections)
+ * function.
  *
- * @param code - projection's SRS code (only used internally by the Proj4js
- * library)
- * @param proj4def - Proj4 definition string for the projection to use
+ * @param code - Named alias of the currently defined projection.
+ * @param proj4def - Proj4 or WKT string of the defined projection.
  */
 export const defs = (code: string, proj4def: string) => proj4.defs(code, proj4def);