search

uber / h3-js

h3-js provides a JavaScript version of H3, a hexagon-based geospatial indexing system.
https://uber.github.io/h3
Apache License 2.0
867 stars 78 forks source link

Documentation of the [lat, lng] tuple #152

Closed wiese closed 2 years ago

wiese commented 2 years ago

Many methods (e.g. cellToLatLng()) return a tuple of latitude, longitude.

They are documented as returning a variable-length array of numbers (number[]), while in practice they should return a fixed-length array.

Is there a reason not to document this as [number, number] instead? This could help in TS projects with strictly configured index access.

Thanks

Further reading

nrabinowitz commented 2 years ago

Good idea, I can add this pretty quickly. I think it makes more sense in output than input - partly because requiring tuples in input can lead to annoying type errors, and partly because e.g. polygonToCells might use GeoJSON as input, which can technically include a third element in coords for altitude (though the H3 library would ignore it at present).

nrabinowitz commented 2 years ago

...I took a quick swing at this, and ran into the same issue noted in the discussion you linked. The problem is, JSDoc doesn't technically support tuples, leading tsd-jsdoc to fail when trying to parse them, so we can't easily support tuples unless we switch from auto-generating types with tsd-jsdoc to another approach (hand-crafting the libdef, or converting the underlying code to TS and generating the libdef from there). I'll take a quick look to see if there's an alternative generated solution here, but otherwise I'm less willing to change the whole type generation approach to fix this issue - sorry about that.

boredland commented 2 years ago

converting the underlying code to TS

Would such a change be something we could do? I'd be in for it.

nrabinowitz commented 2 years ago

converting the underlying code to TS

Would such a change be something we could do? I'd be in for it.

I have an alternate option here (#153) generating the .d.ts files with TS. It's a little awkward but solves this issue. Converting to TS should be feasible, but I think it would require re-engineering the build, which could be a pain. I'd be open to PRs for this, as long as they create all the same bundles we do now.