search

geotiffjs / geotiff.js

geotiff.js is a small library to parse TIFF files for visualization or analysis. It is written in pure JavaScript, and is usable in both the browser and node.js applications.
https://geotiffjs.github.io/
MIT License
878 stars 183 forks source link

A solution for the docs generation error #298

Closed MichaelBuhler closed 2 years ago

MichaelBuhler commented 2 years ago

This PR fixes the docs build error introduced by #296.

As discussed, this PR adds a dependency on jsdoc-plugin-intersection (see npm or GitHub) which rewrites any defined & intersection types as a | union types before docs generation, so that the JSDoc Closure Compiler can parse it.

I ran into an additional problem with the Closure Compiler not supporting types like (A | B) | C. Nor does it support (A | C) | (B | C). So I had to be more verbose with intermediate typedefs, like C AC = A | C BC = B | C so that I could use AC | BC.

The resulting TypeScript type is still correctly output as an intersection, like so:

export type Dimensions = { height: number; width: number };
export type TypedArrayWithDimensions = TypedArray & Dimensions;
export type TypedArrayArrayWithDimensions = TypedArray[] & Dimensions;
export type ReadRasterResult = TypedArrayWithDimensions | TypedArrayArrayWithDimensions;

The generated docs are slightly incorrect, so I added come comments/descriptions/explanations, as seen here:

If this is too verbose, let me know how to change it. Another way to solve the problem is by defining a class to be used as the return type of .readRasters().

constantinius commented 2 years ago

Looks good to me. Thanks for the effort!