Ember specific documentation

[tim-evans]

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)

[pzuraq]

So it seems like you've basically made a custom Ember doc generator? That's awesome 😄

The plugin system is pretty generic so you could definitely open source the base generator, and then create a plugin to convert the format you've established to the one that ec-addon-docs consumes. I described the data format in this PR and you can also look at the ember data models we include to get some idea of how it all works. There are two plugins currently:

• YUIDoc
• ESDoc

The plugin system works similarly to ember-cli-deploy's, I haven't had time to document it much but will try to get around to it soon! You can always ask questions here on on Slack (#ec-addon-docs)

Edit: Should also note, we will be removing the helpers type from Modules, it turns out helpers can be functions or classes (as in ember-intl) so we'll just document them as if they were standard modules and let users figure out the best way to document them

[tim-evans]

Thanks @pzuraq ! That looks very nice 👍

Yeah, the documentation generator is a blend of parsing the documentation using doctrine, and parsing the code using babylon. I'm sort of a newbie at traversing ASTs efficiently, but it's so far been very productive

[tim-evans]

To be a bit clearer, I think this would be good project to be under the ember-learn umbrella. If that sounds like something people would be interested in, I would love to collaborate and get that happening.

[pzuraq]

Ah, I'm not an ember-learn team member so can't say for sure then, but I definitely think if the project matures it could be really great. So far it looks like ESDoc is the top contender for future ES6+ documenters, but its maintainer is very stubborn and refuses to add other collaborators so it's stagnated at times. Having a good, future thinking, generic doc generator that we can count on would be awesome 😃

[tim-evans]

Yep! I'll monitor this and be in touch~

If we decide to open up the ember docs generator, I'll attach it here ✨

[acorncom]

@tim-evans I am on the learning team and don’t see that we would be at all opposed. What I would suggest though is that you split your work out on your end and start iterating on it and we can figure out where it would be best for it to live as it matures.

Don’t block waiting for us in other words 😉

One thing I’ve been wondering about is whether we would want to be using TypeDoc in some way. Would that work better than ESDoc? Some folks I know have raved about it, but I haven’t had the time to take a look yet ...

[pzuraq]

This is why we decided to go with the plugin system strategy, there just isn't a clear winner yet. The idea is that we can create a generator which uses the output from whatever documenter there is and convert it to the common format (which I've been trying to make match Typescript's type system and things, just for that)

The added bonus here is that's where we can add meta data, like Arguments/Yields and whether or not a class is a component, to the payload. That way we can rely on generic JS documenters as well, and still get the benefits of Ember specific documentation. That said, I think the possibilities of a documenter built for Ember from the ground up would be pretty amazing!

Edit: Also we should definitely make a Typedoc plugin

[tim-evans]

@acorncom awesome! I'll discuss with coworkers next week and let y'all know what the results are. What I have will actually add a whole lot of metadata to documentation, and may not actually work with some of the documentation schema– it's quite a bit more extensive.

[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.

[dfreeman]

@acorncom I've been mulling over how to best implement a Typedoc plugin—it's something I'd very much like to have 🙂

The double-edged sword with Typedoc is that its generation process involves actually running the TS typechecker against your project in order to get all the inferrable type information for producing docs. This is great in that it minimizes the amount of boilerplate authors need to add to get robust documentation, but the flip side is that a naive integration with addon-docs would impose the full cost of loading and performing type inference for your entire addon on each rebuild.

There are some changes brewing in ember-cli-typescript to move its compilation in-process (for unrelated reasons); one bonus I'm hoping to be able to pull from that work would be the ability to get our hands on the actual Program instance there in order to feed it to Typedoc and avoid all that duplicated work.

[tim-evans]

@dfreeman yeah, what I'm currently doing is running the code through babylon, which is part of the babel transpilation process. Fortunately, this is pretty quick, even with my naïve implementation.

[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.