Clarify behavior of some existing turf modules

[twelch]

• doc update
• Have read and followed the steps for preparing a pull request.

Resolves #2638 (squareGrid/rectangleGrid/triangleGrid/pointGrid)
Resolves #2643 (area, helpers/earthRadius)

In addition, to clarifying the behavior of some modules, it takes a shot at replacing stale lists of units in JSDocs, with a link to another page with the full list of Turf units accepted.

Right now I have it link directly to the turf/helpers source file, which isn't optimal, so I'm open to feedback. The link should be durable. One idea is to create a Units page in turf-www that provides a maintained full list of units. I think you may have originally had this idea @smallsaucepan, thoughts?

[smallsaucepan]

There are a handful of miscellaneous classes defined in turf e..g Units, QuadratAnalysisResult. I'll take a look to see if there's a way to get documentation.js to generate a shared page for those automatically. Otherwise, yeah we might just have to add a manually updated page to the website and link to that. Will get back to you.

[twelch]

Not sure if it's overkill, but @smallsaucepan I've started playing a little bit with a tool for querying the abstract syntax tree of a Typescript file. Try to access the string literals for the type declaration. Haven't figured it all the way out, but potential.

import fs from "fs-extra";
import { ast, query } from '@phenomnomnominal/tsquery';

(async () => {
    try {
      const helpersTs = fs.readFileSync("packages/turf-helpers/index.ts", "utf8").toString()
      const theAst = ast(helpersTs);
      const tNodes = query(theAst, 'TypeAliasDeclaration');
      console.log(tNodes.length); // 7
    } catch (e) {
      console.warn(e)
    }
})();

I pasted the helpers index code into this viewer to get a sense for the tree and how to access what I want - https://ts-ast-viewer.com/

[smallsaucepan]

Thanks @twelch that's actually a handy debug tool.

[twelch]

@smallsaucepan thanks for your feedback. I think this PR is ready. I've cleaned up the JSDocs further. And something new, as a stopgap, I've also manually created a README_UNITS.md file in turf-helpers with all of the supported turf UNITS and AREA_UNITS. I link to this readme is now in each of the 4 grid functions in this PR.

Follow-on work:

• I do think the unit name extraction can be automated, as part of generate_readmes.ts, and inserted into the README markdown. I have some initial work in the extract-units branch but it's WIP, the AST queries aren't quite working right.
• Swap a link to this file into all of the other modules that support units.

[mfedderly]

Probably needs a run of pnpm run docs to get the README.md's generated. Otherwise I'm a big fan of all of these changes.

[mfedderly]

is this link going to work from the public docs site? (I think its going to send them to the github markdown page instead of staying on the docs website) Maybe that's fine for now, but it won't be versioned cleanly if we do it this way.

[twelch]

When clicking the link from the public docs website, they will be sent to the markdown page, for now. #2694 is meant to take it the rest of the way and extract the units into the turf-helpers README

[mfedderly]

sounds good. happy to merge this as is and give you some breathing room to get that in a good place.

[smallsaucepan]

@twelch and @mfedderly, has this actually resolved #2638? I believe the implementation needs to be rolled back. It's not just a documentation tweak.

[twelch]

I chose doc clarity to resolve that issue. Not as a solution but an improvement over confusing docs. Rollback could certainly happen but wont fully solve user needs either as the change was made for a reason. I had started a discussion on grids that I think might yield the right path forward.

[smallsaucepan]

@twelch, I don't agree with this approach. The updates to the documentation don't clear up the situation or explain what is happening or how to compensate for it.

The original change was made to cover an edge case where someone was trying to create a grid covering the entire planet (#2079). The fix for that (#2106) now produces visibly deficient results for what is probably a high proportion of users.

We should reopen #2638 until we at least decide how grids should work. I did reply to your discussion with follow up questions, though have not seen any activity since.

[twelch]

@smallsaucepan I appreciate your thoughts. My intention was to create a new issue with backlinks, It's been a busy few days for me I just hadn't gotten to yet, but I'm happy to reopen the previous if you think that's a better fit.

[smallsaucepan]

Thanks @twelch. Our best short term solution may be to roll back to the 6.5.0 grid implementation, which would close #2638 but reopen #2079. Might be the lesser of two evils.