Improve Component API Doc documentation

[andrewpye]

Perhaps this is coming from my inexperience with JSDoc, but I'm getting unexpected results regarding accessibility level in the generated API documentation for my components. Say I have this component:

// my-component.js
import Component from '@ember/component';

/**
 * Some new component I made.
 *
 * @class my-component
 * @public
 */
export default Component.extend({
  /**
   * Some public field
   *
   * @property publicField
   * @type {String}
   * @default null
   * @public
   */
  publicField: null,
});

I would expect the public field to be visible by default when the documentation page loads; however, the generated API documentation page for this component looks like this:

and the public field only becomes visible after clicking the internal checkbox:

Is there a way to make fields visible as public?

[pzuraq]

So it's not at all you here, we actually have introduced some new concepts specifically for components in Ember because they don't actually operate like normal classes 😄

A component's public API consists of Arguments and Yields, rather than properties, methods, and accessors (getters/setters). Arguments can be tagged using the @argument tag instead of @property or @field, and will be automatically discovered by ESDoc if you're using an @argument decorator.

Semantically, the difference here is that from a component's perspective, fields are always protected - they can only be accessed by subclasses of the component. This is actually enforced in component's defined with native class syntax now, and will be enforced with Glimmer components in the near future with @arg='foo' syntax and arguments being passed onto the args hash, and it gives users a way to distinguish between fields which were meant to be overriden - the public API - and fields which just happened to be overrideable, but were actually meant to be internal.

Actions are also Arguments in this world - you pass a closure action (function) or string in as an argument to the component, which then sends that passed in value.

[pzuraq]

I'm going change the title of this issue to focus on improving the documentation story around API docs, it's definitely not clear reading through things right now that this is how it's supposed to work.

[andrewpye]

@pzuraq thanks so much for the detailed explanation, that does make sense! 🙌

[csprocket777]

Is there an example of using the @argument decorator? I'm using the esdoc generator and I'm not seeing ANY effect on putting decorators in my code to guide the doc generation process.