Turf: docs incompatible with function namespaces

[noerw]

As a new user it is totally unclear, which functions are available in the main turf package, and which functions need to be separately loaded in external packages:

After some lengthy experiments it seems to me, that all functions listed in the docs are included in turf, except for the ones in section _Meta_. These can be called on the package turf-meta.
Except for turfMeta.getCoord() which is nonexistent in the code it seems. instead the function turfMeta.coordAll() is available, but listed under _Assertions_ in the docs..?!

So there is definitely some clarification needed:

• what functions can be used by default
• what functions need to be loaded separately
  
  
  
  • from which package
  
  
• a list of external packages
• a best practice to add functions from external packages to the turf namespace

edit: I'm using the latest npm packages [email protected] and [email protected]

[tmcw]

Hi Norwin!

Yep, you're totally right: the documentation should be much clearer about how to call methods. getCoord is included in the turf-invariant package, and this should also be mentioned more clearly.

Noting that these tasks need doing. I'll do them myself if I get the time, but I have tens of other projects to maintain, so can't guarantee any timeframe on that. If you'd like these clarifications to be completed sooner, you're very welcome to contribute to the project - both turf & turf-www, where the docs are generated, are open source projects that happily accept contributions!

Thanks,

Tom

[ThomasG77]

Diagnostics

I would need a feedback on the current state I discovered for then contributing.

In the docs

...
...

• META
  
  
  
  • propEach (1) (_turf-meta_)
  
  
  • coordEach (1) (_turf-meta_)
  
  
  • coordReduce (1) (_turf-meta_)
  
  
  • featureEach (1) (_turf-meta_)
  
  
  • getCoord (1) (_turf-invariant_ => wrong in the doc?)
  
  
• ASSERTIONS
  
  
  
  • featureOf (1) (_turf-invariant_)
  
  
  • collectionOf (1) (_turf-invariant_)
  
  
  • bbox
  
  
  • circle (1) (_turf-circle_ => wrong in the doc?)
  
  
  • geojsonType (1) (_turf-invariant_)
  
  
  • propReduce (1) (_turf-meta_ => wrong in the doc?)
  
  
  • coordAll (1) (_turf-meta_ => wrong in the doc?)
  
  
  • tesselate
  
  

(1) Not in default turf.min.js

Conclusion:

META

Quite consistent except for getCoord in _turf-invariant_ and propReduce and coordAll in ASSERTIONS...

ASSERTIONS

• bbox and tesselate are not related to _turf-invariant_ but provide by the default turf build
• circle has it own package
• some assertions are in _turf-meta_, some other in _turf-invariant_ => consistency choice?

In the code

Missing doc in official site (need confirmation):

• _turf-center-of-mass_
• _turf-line-slice-along_
• _turf-idw_

[gmaclennan]

Having wasted some time twice now (I forgot from last time) wondering why some functions were not working, would love to help fix the docs on this. However, I'm not clear enough on the project structure to suggest updates to the docs. I don't understand where the turf-junkyard org fits into this, and some of these functions seem to be in there. Meanwhile there are some references to turf-helpers that I can't find anywhere. Is everything in both the TurfJs org and the turf-junkyard org supposed to be in the docs? Is turf-junkyard for tools that are deprecated?

[ThomasG77]

Just ignore "turf-junkyard". It stores some old functions. Now, the source of truth is https://github.com/Turfjs/turf/tree/master/packages See http://www.macwright.org/2016/07/08/lerna-npm-organizations-new-wave-modularity.html for more info (monorepo approach with lerna)

[DenisCarriere]

A good place to start is looking into each package from the latest @turf/turf repo.

https://github.com/Turfjs/turf/tree/master/packages

That source code is reflected in the official docs http://turfjs.org/docs/.

[gmaclennan]

Thanks for the pointers! I'd been installing with npm install turf as the website says, which explains why I was on v3.0.14 and not the latest. Is there a CDN link for the latest @turf/turf v3.5.2, it would make sense that the docs referenced that version.

[tmcw]

Current fixes:

• turfjs.org points to npmcdn of turf and says to install the namespaced module
• turf-junkyard repo now has a much more pushy name, description, and url to try to combat misunderstandings. It also, unfortunately, just got flagged by GitHub as potential spam. Once it's unflagged, I'll go through each repo in the org and make it clearer that all the repos are deprecated.

We have the option of deleting the turf-junkyard projects: in good internet spirit, I've been trying to keep links to their issues alive and avoid unnecessary 404s, but given previous experience this benefit might not be worth the confusion it introduces.

[rowanwins]

I believe this could now be marked as closed given the recent updates to the docs, I hope they are much clearer in this regard.
cc @DenisCarriere

[DenisCarriere]

👍 previously I added invariant to Turf, now I've also included meta to Turf that way those methods are also built for the web.