Better docs on errors

matafokka · Sep 7, 2022 · 05caa53 · 05caa53
1 parent 8bad131
commit 05caa53
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 15 deletions.
diff --git a/main.js b/main.js
@@ -82,20 +82,24 @@ const toFixed = (n) => {
  */
 
 /**
- * Errors that have occurred during converting geokeys. Since GeoTIFF supports EPSG codes that just can't be applied to an image. On top of that, it's possible to craft faulty GeoTIFF. So errors are unavoidable.
+ * Errors that have occurred during conversion.
  *
- * In most cases, you can just warn user that their file might be used wrongly. In specialized cases, it's your choice how to report those errors.
+ * Apart from listed properties, there's properties that named after geokeys with `NotSupported` suffix, i.e. `ProjFalseOriginLongGeoKeyNotSupported`. Values are EPSG codes assigned to those keys. These errors mean that the specified EPSG code is either not supported by this library, or it's new and hasn't been added yet. If it's the latter, please, create an issue at https://github.com/matafokka/geotiff-geokeys-to-proj4
  *
  * If an error has not occurred, it won't be present in this object.
  *
- * There're unspecified properties that named after geokeys with added `NotSupported` suffix, i.e. `ProjFalseOriginLongGeoKeyNotSupported`. Values are EPSG codes assigned to those keys. These errors means that specified EPSG code is either not supported by this library or are new and hasn't been added yet.
+ * How to process these errors:
+ *
+ * 1. If it's your program's user's GeoTIFF, show an error message.
+ * 1. If it's your GeoTIFF, fix it in a GIS.
+ * 1. If you're sure that file is fine or want to discuss it, please, create an issue at https://github.com/matafokka/geotiff-geokeys-to-proj4
  *
  * @typedef {Object} module:geokeysToProj4.ConversionErrors
- * @property {boolean} bothGCSAndPCSAreSet `true` When both `GeographicTypeGeoKey` and `ProjectedCSTypeGeoKey` geokeys are set. In this case, `GeographicTypeGeoKey` is used. This happens only if GeoTIFF has been specifically crafted to be faulty.
+ * @property {boolean} bothGCSAndPCSAreSet `true` When both `GeographicTypeGeoKey` and `ProjectedCSTypeGeoKey` geokeys are set. In this case, `GeographicTypeGeoKey` is used. The cause of this error is broken geokeys.
  * @property {number} CRSNotSupported Specified CRS can't be represented as Proj4 string or it's new and hasn't been added to this library. Value is EPSG code of specified CRS.
- * @property {number} GeogLinearUnitSizeGeoKeyNotDefined Geokey `GeogLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. This happens only if GeoTIFF has been specifically crafted to be faulty.
- * @property {number} GeogAngularUnitSizeGeoKeyNotDefined Geokey `GeogAngularUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogAngularUnitSizeGeoKey`. In this case, every other key using this one assumed to be using degrees. This happens only if GeoTIFF has been specifically crafted to be faulty.
- * @property {number} ProjLinearUnitSizeGeoKeyNotDefined Geokey `ProjLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `ProjLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. This happens only if GeoTIFF has been specifically crafted to be faulty.
+ * @property {number} GeogLinearUnitSizeGeoKeyNotDefined Geokey `GeogLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. The cause of this error is broken geokeys.
+ * @property {number} GeogAngularUnitSizeGeoKeyNotDefined Geokey `GeogAngularUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogAngularUnitSizeGeoKey`. In this case, every other key using this one assumed to be using degrees. The cause of this error is broken geokeys.
+ * @property {number} ProjLinearUnitSizeGeoKeyNotDefined Geokey `ProjLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `ProjLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. The cause of this error is broken geokeys.
  * @property {number} conversionNotSupported Conversion specified in `ProjectionGeoKey` is not supported by this library. Value is EPSG conversion code.
  * @property {number} coordinateTransformationNotSupported Transformation specified in `ProjCoordTransGeoKey` is not supported by this library. Value is projection code. See http://geotiff.maptools.org/spec/geotiff6.html#6.3.3.3 for more information.
  */

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "geotiff-geokeys-to-proj4",
-  "version": "2022.09.06",
+  "version": "2022.09.07",
   "description": "A library that converts GeoTIFFs geokeys to Proj4 string",
   "main": "main-dist.js",
   "types": "types.d.ts",

diff --git a/types.d.ts b/types.d.ts
@@ -167,33 +167,37 @@ export interface GeoKeys {
 }
 
 /**
- * Errors that have occurred during converting geokeys. Since GeoTIFF supports EPSG codes that just can't be applied to an image. On top of that, it's possible to craft faulty GeoTIFF. So errors are unavoidable.
+ * Errors that have occurred during conversion.
  *
- * In most cases, you can just warn user that their file might be used wrongly. In specialized cases, it's your choice how to report those errors.
+ * Apart from listed properties, there's properties that named after geokeys with `NotSupported` suffix, i.e. `ProjFalseOriginLongGeoKeyNotSupported`. Values are EPSG codes assigned to those keys. These errors mean that the specified EPSG code is either not supported by this library, or it's new and hasn't been added yet. If it's the latter, please, create an issue at https://github.com/matafokka/geotiff-geokeys-to-proj4
  *
  * If an error has not occurred, it won't be present in this object.
  *
- * There're unspecified properties that named after geokeys with added `NotSupported` suffix, i.e. `ProjFalseOriginLongGeoKeyNotSupported`. Values are EPSG codes assigned to those keys. These errors mean that specified EPSG code is either not supported by this library or are new and hasn't been added yet.
+ * How to process these errors:
+ *
+ * 1. If it's your program's user's GeoTIFF, show an error message.
+ * 1. If it's your GeoTIFF, fix it in a GIS.
+ * 1. If you're sure that file is fine or want to discuss it, please, create an issue at https://github.com/matafokka/geotiff-geokeys-to-proj4
  */
 export interface ConversionErrors {
 	/**
-	 * `true` when both `GeographicTypeGeoKey` and `ProjectedCSTypeGeoKey` geokeys are set. In this case, `GeographicTypeGeoKey` is used. This happens only if GeoTIFF has been specifically crafted to be faulty.
+	 * `true` when both `GeographicTypeGeoKey` and `ProjectedCSTypeGeoKey` geokeys are set. In this case, `GeographicTypeGeoKey` is used. The cause of this error is broken geokeys.
 	 */
 	bothGCSAndPCSAreSet: boolean;
 	/**
 	 * Specified CRS can't be represented as Proj4 string or it's new and hasn't been added to this library. Value is EPSG code of specified CRS.
 	 */
 	CRSNotSupported: number;
 	/**
-	 * Geokey `GeogLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. This happens only if GeoTIFF has been specifically crafted to be faulty.
+	 * Geokey `GeogLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. The cause of this error is broken geokeys.
 	 */
 	GeogLinearUnitSizeGeoKeyNotDefined: number;
 	/**
-	 * Geokey `GeogAngularUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogAngularUnitSizeGeoKey`. In this case, every other key using this one assumed to be using degrees. This happens only if GeoTIFF has been specifically crafted to be faulty.
+	 * Geokey `GeogAngularUnitsGeoKey` is set to user-defined, but user hasn't specified `GeogAngularUnitSizeGeoKey`. In this case, every other key using this one assumed to be using degrees. The cause of this error is broken geokeys.
 	 */
 	GeogAngularUnitSizeGeoKeyNotDefined: number;
 	/**
-	 * Geokey `ProjLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `ProjLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. This happens only if GeoTIFF has been specifically crafted to be faulty.
+	 * Geokey `ProjLinearUnitsGeoKey` is set to user-defined, but user hasn't specified `ProjLinearUnitSizeGeoKey`. In this case, every other key using this one assumed to be using meters. The cause of this error is broken geokeys.
 	 */
 	ProjLinearUnitSizeGeoKeyNotDefined: number;
 	/**