Ember specific documentation

Hi! I was talking to @samselikoff at EmberConf and was working on some stuff for a styleguide internally at Condé. Currently, I have some code that will extract out positional / named parameters from helpers and generating appropriate documentation according to that. I’m wondering if it would be good to move that to an open source repository that the ember-learn team can collaborate on so we can all get the benefits.

The current bit of code I have does the following:

• Pulls the type of the module according to Ember semantics (if it’s in app/components it’s a component)
• Pulls public / private info according to the name of the file (if it starts with a - or it’s nested, since nested components usually imply that they’re private). With the new module layout, this will be much easier and we can identify whether they are global / local
• Parses the javascript to identify positional and named parameters in helpers, then mapping those names back to the parameters named in the JSDoc:

  import { helper } from '@ember/component/helper';
  /**
     Say hello!
     @param {string} name Who to say hello to
   */
  export function hello([name]) {
     return `Hello, ${name}`;
  }
  export default helper(hello);
  

  The helper above would generate a doc blob that looks like:

  {
    type: 'helper',
    name: 'hello',
    description: '<p>Say hello!</p>',
    parameters: {
      positional: [{
        name: 'name',
        type: 'string',
        description: 'Who to say hello to'
      }]
    }
  }
  

• Compiles @example blocks to make it easy to render these in documentation. I like this because it enforces that not only the documentation is up to date, but the actual code examples for developers are up to date.
• Automatically provides a list of injected services / controllers on a given module.

I think that most of this could be very valuable to the community. However, I really just want to get something up and running quickly for our team so we can start wrangling some of the components we have. The code I wrote is… brittle 😅 and a bit silly. I would very much enjoy sharing this workload with the many smart and thoughtful people working on this project, but would first like to have a bit of a conversation if our goals align.

Most of this work is tough and requires deep knowledge on all the different ways that people can organize Ember projects.

For some transparency into what my plans are, I’m providing a small list of things that I’d like our documentation parser to do:

• Provide a list of modules that depend on a service. This will help with sprawl / aggressive service injection in applications.
• Pull default parameters from JS instead of the @param doc. This way, the docs are never out of date.
• Provide type information on {{yield}} blocks, if possible (we could possibly interpolate what types flow through glimmer by looking at the documentation on the component)

[tim-evans]

Closing this; for those interested, see https://github.com/CondeNast-Copilot/ember-docs

Our goal on the repo is to provide a solid baseline to use in ember-cli-addon-docs and friends.

[pzuraq]

If there are features that the current docs generators don’t support and you’d like to add, definitely open to that. The idea is to be extensive and Ember focussed, even if the backing documenter can’t support it.

For instance, YUIdoc can’t support decorators, but we still want to support them because ESDoc and more modern generators can.