New component with docs of a given component arguments

[josemarluedke]

So, this is a feature request of sorts. Hopefully I'm able to describe what I would like to have from addon-docs.

So, auto generation of api documentation using JSDoc or ESDoc is great. I think we could use that to generate documentation of all the arguments that a component can take.

The problem I see today with the API docs section, is that usually I will have a documentation page for a component with several live demos. Having the documentation of the arguments of these components in a separated page is not the best experience. I would expect a "table" with all the available arguments for that component, having: type, description, default value and etc.

A great example of this is what @pranavliag is doing with ember-elements. Here is one example.

I would like to have a component from addon-docs that I can use in one of my custom pages that would include the table with the documentation of the arguments. I would just pass the component name to it and it would take care of rendering that list of arguments.

We should also be looking forward to support glimmer components args. It will be interesting if folks are using TypeScript to define their arguments interface, then we can probably extract that info somehow.

[pzuraq]

So we already do this currently, a bit. We treat components a bit differently than standard classes - instead of showing users their fields and methods, we show them their arguments and their yields, which are really the public API of the component. The Ember Table docs are a great example of this.

You should be able to get this with the YUIDoc and ESDoc adapters by annotating a field with @argument, and for the yields you can annotate the class itself with @yield for each individual yield. Maybe this should be documented a bit better?

[josemarluedke]

@pzuraq This is great! Yeah, I'm familiar with that feature. But what I would like to see is a way to extract that section from the API page and embed into a "guide" page.

For example, consider the screenshot bellow to be the component I'm talking about. I would like to put that into, let's say the "Header > Columns" page. With that, users reading about the head would have the arguments to that component right there. (Maybe not the best example, but I think it illustrates what I mean.)

[pzuraq]

I don't think this information belongs on the guide page. The API page is exactly what this type of page is for, and guide pages are for in depth and live examples. If there's some reason the API docs aren't covering these needs, maybe we can improve them?

[pzuraq]

Keep in mind also that once template imports become a thing, addon users will actually need know the import paths to a given component. I think the sidenav reflecting the module path is really important for this, it allows you to quickly navigate the addon based on looking at existing import paths, and allows you to quickly figure out where something should be imported from based on that.

Maybe we could do some work to make the markdown above the API docs more dynamic/guide-like, if the goal is to consolidate?