Classes + .d.ts

[tmcw]

What would it take to

• Add types and classes to turf's hierarchy
• document turf

Options

• flow doesn't yet support exporting type data as json, so wouldn't be useful for docs: Dump type annotations as JSON? facebook/flow#208
• tern's typescript integration is broken typescript file moved ternjs/tern#468 and doesn't work 'online' only as a transform.
• flow has a feature that transforms jsdoc comments into flow types Type annotations in comments? facebook/flow#3

Quest

TypeScript has some warts:

• Suggestion: multi-file external modules microsoft/TypeScript#17
• Export a module with require() microsoft/TypeScript#1598 (comment)

Upstreams

• tern bug Move position of doc property ternjs/tern#471
• tern integration oddness functional condense() method ternjs/tern#472
• jsdoc apparently does nothing about node Improve static analysis of require() calls jsdoc/jsdoc#863
• flow bug "inconsistent use of library definitions" facebook/flow#185

name	commonjs support	documentation strings	types	typechecking	bugs
tern	yes, great	yes	yes	no	yes
jsdoc	nope	yes	yes	no	?
flow	yes	no	yes	yes	yeahh
typescript	nope	yes	yes	yes	yeahh

[tmcw]

Doc progress:

See doc docs for tips on how to contribute

• isClockwise
• isolines
• isobands
• merge
• convex
• within
• concave
• count
• erase
• variance
• deviation
• median
• min
• max
• aggregate
• flip
• simplify
• sum
• average
• bezier
• tag
• size
• sample
• jenks
• quantile
• envelope
• square
• midpoint
• buffer
• center
• centroid
• combine
• distance
• explode
• extent
• bboxPolygon
• featurecollection
• filter
• grid
• inside
• intersect
• linestring
• nearest
• planepoint
• point
• polygon
• reclass
• remove
• tin
• union
• bearing
• destination
• hex
• kinks
• pointOnSurface
• area

/cc @morganherlocker @lyzidiamond would love help on this when you get time, there are many modules to hit.

[mourner]

@tmcw btw, I'd love to see a hey post on your docs research and comparison of different approaches.

[tmcw]

Y, definitely worth a post, will pull it together in a bit.

[tmcw]

new thing: we have rpl-www installed for self-running and live-codable documentation. trick is to

• don't use require() - this isn't node, so it won't be available
• turf is available as a library by default
• use //= comments to expose things

so for example:

var points = turf.featurecollection([
  turf.point(10.1953125, 43.75522505306928),
  turf.point(10.404052734375, 43.84245116699039),
  turf.point(10.579833984375, 43.6599240747891),
  turf.point(10.360107421875, 43.51668853502909),
  turf.point(10.140380859375, 43.58834891179792),
  turf.point(10.1953125, 43.75522505306928)]);

var result = turf.featurecollection(
  points.features.concat([turf.convex(points)]));
//=result

The line //=result is like saying 'make a map with what's in the variable result right now'.

• I've been using turf.featurecollection a bunch to show before & after on the same map, but you can also do multiple maps by using //= comments twice or more
• esprima seems to prefer semicolons. I'll look for the upstream cause but for now, non-asi style javascript is safest

[lyzidiamond]

Let's knock this out! Goals of this walk-through:

• Move examples away from Null Island
• Fix any tests that have broken polygons
• Conform styling (dashes, line-breaks)
• For any modules that are confusing or have questions/issues on how to implement, comment here.
  • aggregate
  • average
  • bbox-polygon
  • bearing
  • bezier
  • buffer
  • center
    • Add styling to example to show difference between points
  • centroid
  • combine
  • concave
  • convex
  • count
  • destination
  • deviation
  • distance
  • envelope
  • erase
  • explode
  • extent
  • featurecollection
  • filter
  • flip
  • grid
  • hex
  • inside
  • intersect
  • isobands
  • isolines
  • jenks
  • kinks
  • linestring
  • max
  • median
  • merge
  • midpoint
  • min
  • nearest
  • planepoint
  • point
  • point-on-surface
  • polygon
  • quantile
  • reclass
  • remove
  • sample
  • simplify
  • size
  • square
  • sum
  • tag
  • tin
  • union
  • variance
  • within

cc @tmcw @morganherlocker

[morganherlocker]

• isolines is super difficult to use; I'll try to fix it up and document it better

[lyzidiamond]

• flip mutability issue (documented here and here) is preventing a working example

[tmcw]

Fixed flip mutability, we should start doing dev releases so we can rebuild the site's examples with pre-released bugfixes.

[tmcw]

Removed isClockwise from this list because it was removed from turf's public-facing api in #176

[tmcw]

Replaced all readFileSync()-using examples today and introduced turf.random to make more examples viable. Given the iffy status of the statsy modules (median min max variation average) and the tediousity & quantity of this work, I'm leaning towards hitting just a few more and jumping off this for anyone else to jump on and review.

[tmcw]

The deed is done (initially): just pushed all turfjs modules, syncing all versions and rewriting all readmes with doxme.

[lyzidiamond]

Just completed a second run-through of the documentation. I feel comfortable saying we're good to go!

[tmcw]

👍 docs are launched and I think we can consider this stage complete ✋ all around!

[morganherlocker]

🎉 awesome work @lyzidiamond @tmcw! This is a huge step that took an enormous amount of effort.

[jseppi]

Yeah, it's super great and provides a good model for other projects! 👏