Documenting top level ES module items

[dfreeman]

Suppose I'm writing an ES2015 module with some top level exports. I could (incompletely) document it roughly along these lines:

/**
  @property MAGIC_VALUE
*/
export const MAGIC_VALUE = 'hello';

/**
  @method compareLength
*/
export function compareLength(input) {
  return MAGIC_VALUE.length - input.length;
}

YUIDoc doesn't really have a notion of functions/values that aren't associated to a class, and its own notion of modules and namespaces don't align with ES2015 modules. If I were to pass this through the doc parser, I'd wind up with output like this:

{
  classes: {},
  classitems: [
    { class: '', itemtype: 'property', name: 'MAGIC_VALUE', ... },
    { class: '', itemtype: 'method', name: 'compareLength', ... }
  ],
  ...
}

Today, yuidoc-to-jsonapi would drop those items on the ground in the conversion, since they don't correspond to a class. Note that, since there is a file associated with each classitem, we can still tell which module they originated from.

In the Ember codebase today, functions like Ember.String.underscore are modeled as being part of a @static String class, and the doc viewer specially presents static classes as "namespaces" (distinct from the YUIDoc notion of the word). With RFC 176 moving from presenting things like Ember.String.htmlSafe to import { htmlSafe } from '@ember/string', though, this starts to feel less natural.

Meanwhile, in ember-cli-addon-docs we're working on making it as easy as possible for addon authors to set up rich documentation for their projects, and part of that is having an API reference. It doesn't feel ideal to have to propose "invent a name for an invisible static class" as the best practice for documenting ES2015 modules.

Fundamentally it feels like YUIDoc may be missing a primitive here, but the project seems relatively stagnant at this point, so adding new concepts there may or may not be in the cards.

Given all that, I'd love to start a conversation about what the ideal way is to model top-level module items, both from the author's perspective and in terms of how it's represented in the JSON API data.

/cc @sivakumar-kailasam

[sivakumar-kailasam]

//cc @locks , @toddjordan

[dfreeman]

As a strawman, I could imagine introducing a new file resource type that gathers up the class-less functions and properties in each file as attributes, the same way classes do. Files could also have a classes relationship to link up with everything that is associated with a class.

For the example above:

{
  data: {
    type: 'file',
    id: 'my-lib/utilities.js',
    attributes: {
      methods: [{ name: 'compareLength', ... }],
      properties: [{ name: 'MAGIC_VALUE', ... }]
    },
    relationships: {
      classes: {
        data: []
      }
    }
  }
}

@samselikoff this might interest you too as we think about ember-learn/ember-cli-addon-docs#12