switch to documentation for documentation

[jfirebaugh]

Example: cutting-room-floor/mapbox-gl-style-lint@06747a4

[mourner]

It's nice for small modules, but I'm not convinced it will look good with https://www.mapbox.com/mapbox-gl-js/api/ — no table layout for methods/properties and many times more verbose / less skimmable.

[tmcw]

no table layout for methods/properties

This is no longer the case

and many times more verbose / less skimmable.

This isn't specific enough to fix

[mourner]

This is no longer the case

I mean methods and properties, not parameters.

Generally, something that takes one row in the current docs will take a whole screen when converted to generated docs without necessarily improving documentation content (more detailed !== better), making the docs much harder to read.

[tmcw]

So... what you're saying is that we should improve doxme? Like, it's software that I wrote and can be improved like other software.

[mourner]

@tmcw yes, I'm now reading about jsdoc and scratching my head around how to make Leaflet-like docs from dox-generated output. :)

[jfirebaugh]

Yeah, likewise I just spent a few hours with dox + doxme and quickly got convinced that they're not going to work very well for OO libraries. There's not really any support in dox for object hierarchies, instance methods, etc. Which is fair, it's a hard problem and dox is aiming for a simple solution for the small module crowd.

See e.g. tj/dox#85 and tj/dox#129.

I was also discouraged by the ad hoc and regexp-driven analysis, which leads to frustrations like tj/dox#150.

[tmcw]

Hm, what about jdoc itself though?

On Tue, Feb 10, 2015 at 8:07 PM, John Firebaugh notifications@github.com
wrote:

Yeah, likewise I just spent a few hours with dox + doxme and quickly got convinced that they're not going to work very well for OO libraries. There's not really any support in dox for object hierarchies, instance methods, etc. Which is fair, it's a hard problem and dox is aiming for a simple solution for the small module crowd.
See e.g. tj/dox#85 and tj/dox#129.

I was also discouraged by the ad hoc and regexp-driven analysis, which leads to frustrations like tj/dox#150.

Reply to this email directly or view it on GitHub:
#952 (comment)

[jfirebaugh]

Yeah, jsdoc itself seems flexible enough. Here's what I cooked up for mapbox-directions.js based on a rudimentary understanding of jsdoc.

[tristen]

I started working on this in a jsdoc branch and would love a review. Some immediate open questions:

• For option params that accept an object of specific keys, I'm documenting it like this:

/ **
  * @param {Object} options
  * @param {String} options.type Either `raster` or `vector`
  */

// Not sure if there's a different way to do this but seems to be the jsdoc way.

• For parameters with default options I'm adding it like this 2809fa6#diff-d5506f072d1241401a7e31ff642c1606R92
• It's unclear to me how to document methods that a class inherits? i.e. Events attributed to map
• For methods I am using @method
• Should we be using jsdoc to document private methods?
• If a global (mapboxgs.util) is added here, should a particular method be documented like this? @method mapboxgl.util.supported

[jfirebaugh]

For option params that accept an object of specific keys, I'm documenting it like this

👍 I had not seen that syntax before, but it is documented as the jsdoc way.

For parameters with default options I'm adding it like this

👍

It's unclear to me how to document methods that a class inherits?

@extends (aka @augments)

For methods I am using @method

"This marks an object as being a function, even though it may not appear to be one to the parser." I.e. this tag is mainly a workaround for poor tooling or sketchy code. We'll have to see where we end up with for tooling, but ideally this isn't necessary.

Should we be using jsdoc to document private methods?

You can if you want, but we should do so in a way that excludes them from generated docs, e.g. use single star /* comments and set up the jsdoc processing to read only /** comments.

If a global (mapboxgs.util) is added here

I think we should stop exporting mapboxgl.util. It's a grab bag of miscellaneous stuff that Mapbox GL happens to need right now but that we don't necessarily want to have to support as a public API forever. That goes for mapboxgl.util.getJSON etc too. supported should be exported and documented as mapboxgl.supported.

[tristen]

Added some quick formatting & code highlighting to the rendered API page. @jfirebaugh 🔙 2️⃣ 👈