need to be able to control output order

[jfirebaugh]

Previous discussion: #15 (comment)

@mourner:

Can we make it possible to set an arbitrary order of classes/functions, group them together in chunks with a heading and description (like http://leafletjs.com/reference.html), insert additional narratives?

@tmcw:

yep, that's a top priority. I want to go as far as possible with JSDoc conventions to control this, and if they don't cut it, make minimal additions. JSDoc mainly does this with Tutorials but I hope we can fashion a better system.

[tmcw]

Via discussions, consensus is landing on a standalone "config file" kind of thing that would define this order and eat #85 by allowing people to specify two things other than namespaces: files that are included & parsed as inline documentation, and headers that add more structure to the docs.

Short-term, we need to decide on a format for the structure document

[tmcw]

Sketched out path through this:

Right now the output of documentation-js goes through sort, which gives us our nice and simple alpha sorting. In order for this to do custom sorting, we'll need to pass an option to that stream. For an example of how we've passed options before, see filter_access, a stream that takes access levels and responds accordingly by showing or hiding private docs.

The option enters through the bin args and ends up in the options argument to documentation, where we can pass it to the stream.

How to get this thing to be opinionated about sorting is your call - basically modifying the sort comparator to sort hardcoded items by their order in the config rather than their natural name.

[mourner]

Just stumbled upon an example of this on http://paperjs.org/reference — they're configuring nested hierarchy with a very simple object: https://github.com/paperjs/jsdoc-toolkit/blob/master/templates/paper.js/classLayout.js

[morganherlocker]

Is this issue satisfied by PR #130, which allows a config file that specifies exact order?

[tmcw]

Thoughts on this strawman draft @mourner @morganherlocker @jfirebaugh

• Categories are defined by a category tag. Membership in them is either defined in the category itself, with members, or in the member, with 'incategory'. I would love better words for these concepts: members is close to the existing member tag. maybe children?
• Using the members syntax, you can define order. What if we permitted this in any kind of element, so you can sort children of anything?
• A root tag is used for specifying order at the top level

/**
 * @root
 * @members
 * - additionFunctions
 * - subtractionFunctions
 */

/**
 * @category additionFunctions
 * @title Addition Functions
 * @description
 * These are functions dealing with additio
 */

/**
 * This function adds one to its input
 * @returns {number} added
 * @incategory additionFunctions
 */
function addOne(a) {
  return a + 1;
}

/**
 * @category subtractionFunctions
 * @title Subtraction Functions
 * @members
 * - minusOne
 * - minusTwo
 * @description
 * These are functions dealing with substraction.
 */

/**
 * This function minuses one to its input
 * @returns {number} added
 */
function minusOne(a) {
  return a - 1;
}

/**
 * This function minuses two to its input
 * @returns {number} added
 */
function minusTwo(a) {
  return a - 2;
}

[anandthakker]

How about @categoryDef for the overall category tag, freeing up @category to use instead of @memberof

[jstejada]

any updates on this?

[SunboX]

I'm interested in this, too 😏