Open andrewpye opened 6 years ago
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.
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.
@pzuraq thanks so much for the detailed explanation, that does make sense! 🙌
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.
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:
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?