Documenting Components (arguments, attributes and yield)

[gossi]

I'm looking for a convention/standard to document components, especially targeting these information:

• arguments
• attributes
• yield

for components, template-only components while supporting for java- and typescript. Primarily focused for glimmer components, yet the js-only approach should also be suitable to be applied to ember components, too.

The idea is, that these conventions can be exported into an intermediate format, which itself can be consumed by documentation tools (such as ember-cli-addon-docs or storybook) and on the other hand for tools providing support at our fingertips, e.g. (unstable) ember language server, so we have suggestions through intelli-sense/auto-completion in our preferred editors.

Arguments

Arguments can easily be described as an interface as this already the proposed way for doing this in glimmer components, when using typescript:

export interface InputGroupArgs {
  value: string;
  name: string;
  label?: string;
  error?: string;
  changed?: (value: string) => void;
}

/**
 * An input group is an input field with additional label and error field
 *
 * Usage:
 * 
 * ```hbs
 * <InputGroup @value="abc" @name="given-name" @changed={{this.updateGivenName}} />
 * ```
 */
export default class InputGroupComponent extends Component<InputGroupArgs> {}

JS / Template-only Components

For javascript and template-only components I propose the same approach as above in a component.d.ts file.
Along with that is a side-benefit on top of it, which is type-coverage of your package. Second is, that most editors already use it as input to provide intelli-sense mechanism, even if the choice is to use javascript over typescript.

Alternative

Instead of using a component.d.ts regular JS can be used and special @argument tags in docblock can be used (as it is done today with ember-cli-addon-docs):

/**
 * An input group is an input field with additional label and error field
 *
 * Usage:
 * 
 * ```hbs
 * <InputGroup @value="abc" @name="given-name" @changed={{this.updateGivenName}} />
 * ```
 * 
 * @argument string value
 * @argument string name
 * @argument (string) label
 * @argument (string) error
 * @argument (Function) changed
 */
export default class InputGroupComponent extends Component {}

Drawback of this approach is, that would only work for JS components and is not a solution for template-only components. Second is, that supported types are usually limited to what jsdoc et al. support and not as rich as in comparison to the typesystem typescript offers.

Yield

The type for yield is an array and many people use the first entry to contain an object/hash. First separate between how to document the yield type itself and second where to make the connection between the typed yield and the component.

Typing yield:

import InputGroupLabelComponent from '...';
import InputGroupErrorComponent from '...';

interface InputGroupBuilder {
  Label: InputGroupLabelComponent;
  Label: InputGroupErrorComponent;
}

/**
 * Whether the input group has an error
 */
type IsErrored = boolean;

type InputGroupYield = [
  InputGroupBuilder,
  IsErrored
];

For connecting yield to the component I see two options:

Option 1:

Using a special jsdoc tag @yield (as been done in ember-cli-addon-docs today):

/**
 * [...]
 * 
 * @yield InputGroupYield
 */
export default class InputGroupComponent extends Component<InputGroupArgs> {}

Option 2:

Extend generics to accept a second value as yield:

/**
 * [...]
 */
export default class InputGroupComponent extends Component<InputGroupArgs, InputGroupYield> {}

There is no real benefit from a technical perspective as you are not accessing the yield block from the code as of today and I don't see that happening in the future. Instead would block a slot of the generics, that might be better suited to something else in the future.

As a counter to this, the pair reads coherently as ... extends Component<Input, Output> (which is why I personally like it).

Attributes

There is already an issue open regarding this: #586 (...attributes -- Component API and Discoverability). In speaks about a list of things unknown to the consumer of a component and where passed attributes will end up (if ever). Whereas the argument is that those information are implementation details of the respective component to decide on that.

While I agree this is implementation details I as a consumer still better have some information what I can do use attributes for. It still belongs to the components internals but here are my questions I have when passing down attributes:

• Which element(s) my ...attributes are added to ?
• is it is the most outer one (keep in mind you can have multiple ones)?
• What other attributes are already available?
• What attributes will be overridden by the component?

That's mostly a11y related. Given the element + attribute combination has a massive effect on listener usage: e.g. whether I can use a {{on 'click' ...}} modifier or not.

!!!

Provide Suggestions

!!!

Appendix

You may want to document your component.ts (typescript) or component.d.ts (js / template-only) as described above. Using the generics option for yields, this is how the full example looks like:

import Component from '@glimmer/component';
import InputGroupLabelComponent from '...';
import InputGroupErrorComponent from '...';

interface InputGroupBuilder {
  Label: InputGroupLabelComponent;
  Label: InputGroupErrorComponent;
}

/**
 * Whether the input group has an error
 */
type IsErrored = boolean;

type InputGroupYield = [
  InputGroupBuilder,
  IsErrored
];

export interface InputGroupArgs {
  value: string;
  name: string;
  label?: string;
  error?: string;
  changed?: (value: string) => void;
}

/**
 * An input group is an input control with additional label and error fields
 *
 * Usage:
 * 
 * ```hbs
 * <InputGroup @value="abc" @name="given-name" @changed={{this.updateGivenName}} />
 * ```
 */
export default class InputGroupComponent extends Component<InputGroupArgs, InputGroupYield> {}

---

Let's discuss to fill the blank spots.

[pzuraq]

I've been thinking about this as well recently, and I like the line of thinking that we should be using Typescript to standardize docs. api-extractor has been advancing pretty quickly, and it can document anything that TS understands (including plain JS), so I think it would work pretty well here.

Re: TO-Components, can we potentially declare an TO-component interface that matches Glimmer component's generics, such that you can add a .d.ts file that does something like this?

declare class MyTOComponent extends TemplateOnly<Args, Yields> {}

Re: Yields/blocks, I think that extending generics makes total sense, but I think the typing probably wants to be a bit different for two reasons:

1. Named yields/blocks are right around the corner, so we need to make sure we account for those

2. Blocks are conceptually thought of and taught as callbacks, so I think typing them that way would probably be ideal.

import Component from '@glimmer/component';
import InputGroupLabelComponent from '...';
import InputGroupErrorComponent from '...';

interface InputGroupBuilder {
  Label: InputGroupLabelComponent;
  Label: InputGroupErrorComponent;
}

export interface InputGroupBlocks {
  default(builder: InputGroupBuilder, isErrored: boolean): Template;
}

export interface InputGroupArgs {
  value: string;
  name: string;
  label?: string;
  error?: string;
  changed?: (value: string) => void;
}

/**
 * An input group is an input control with additional label and error fields
 *
 * Usage:
 * 
 * ```hbs
 * <InputGroup @value="abc" @name="given-name" @changed={{this.updateGivenName}} />
 * ```
 */
export default class InputGroupComponent extends Component<InputGroupArgs, InputGroupBlocks> {}

Maybe this type could be an override too, such that if it receives a function directly it assumes it is the default block.

[MichalBryxi]

Just got back from the adventures of trying to make clear the difference between arguments and attributes in doc for built-in-components. And there's a few lions living over there. Even the official documentation for <Input /> has to have this complicated section on difference between those two:

In most cases, if you want to pass an attribute to the underlying HTML element, you can pass the attribute directly, just like any other Ember component.
...
However, there are a few attributes where you must use the @ version.

My take from this excersice is:

• As a consumer of a component I need to know which HTML element is the ...attibutes going to be applied on. As that gives me a hint which ones are allowed in given context.
• As a consumer of a component I need to know which props are attributes and which are arguments and the documentation must not use both for open prop even in cases where they could be used interchangably.
• As a developer of a component I should have a community standard to distinguish between those two. For example: Arguments in backticks have to always start with the @ symbol. e.g: @foo, @bar vs: aria-label.

[pzuraq]

I think this is an excellent point, definitely something to think on more.

I will say, I think that in all cases arguments should be preferred over attributes, if they exist and are documented. So, we should prioritize highlighting the various arguments that exist, and if for instance an @ariaLabel arg existed, it should always supercede manually adding aria-label. The assumption there is that the component author had to do something with the argument value dynamically, and expects you to use the arg.

[gossi]

Attributes

Thanks @MichalBryxi - I also like the comments you added in #586

Regarding this @ariaLabel vs aria-label. If the all the component does is aria-label={{@ariaLabel}} the argument shouldn't be there at all and basically looks very much like code smell, as what you are doing is using glimmer components as ember components 🙈 If instead, you have a @label attribute that is used in different locations or you give your internal <label id="...">{{@label}}</label> and then also use aria-labelledby="..." this is a nice usage instead.

That said, in order to understand this, it is good to understand where my ...attributes are added and which attributes will be added by the component. Stating it like that, documenting it sounds very much like over-engineering.
What you as a developer might give as information is, what the consumer might be adding on top of it.

Yield/Blocks

@pzuraq and had a discussion on discord where I had mostly questions about understanding the new blocks, so let me summarize how to adress them with documentation:

First: Understand the (new) blocks as a callback you pass into the component, which is why using a generic makes sense here. The simplest use case:

export default class FooComponent extends Component<{}, ((x: string, y: string, z: () => void) => Template)>

and the related template:

<Foo as |x y z|>
	{{x}} {{y}} <button {{on 'click' z}}>z</button>
</Foo>

This is the minimal support as we have them now. The type could also be written as (some might prefer this - including me):

interface FooBlocks {
	default(x: string, y: string, z: () => void): Template;
}

export default class FooComponent extends Component<{}, FooBlocks>

This will set us up for having multiple named blocks:

interface FooBlocks {
	main(x: string, y: string, z: () => void): Template;
	title(): Template;
	footer(): Template;
}

export default class FooComponent extends Component<{}, FooBlocks>

and use it as:

<Foo>
	<:title>I'm atop</:title>
	<:main as |x y z|>
		{{x}} {{y}} <button {{on 'click' z}}>z</button>
	</:main>
	<:footer>I go last</:footer>
</Foo>

I pretty much like the yield/blocks part :]

[mehulkar]

Only one thing: please have a path for non TS users!

[pzuraq]

@mehulkar api-extractor can understand plain JS and document it as well. However, it is limited, in that it can't understand the types of values that are provided, and it can't understand values that don't exist (like blocks for instance).

I think the best short-term solution is to say that users should define a component.d.ts file if they want to add documentation for their component. In the medium-to-long-term, api-extractor does output a plain JSON and Markdown format, so we can expand on that by creating tools that can parse doc comment blocks and add additional metadata to the output.

This is, FWIW, how ember-cli-addon-docs API documenters work, but the process there was ad-hoc and very bespoke. I'm worried that if we try to support all of that up front, it'll end up becoming a much larger project. Focussing on using standard types/tooling first I think is likely the going to be most successful path.

[gossi]

@mehulkar I see *.d.ts a solution for js-only, too. You will still write js only components and for docs you'll add the richness typescript offers (as js alone is too limited here).

[jelhan]

Ember CLI Addon Docs allows to add a description per argument / yield.

See here as an example how this looks like in generated docs: https://ember-learn.github.io/ember-cli-addon-docs/docs/api/components/docs-header

Here is the related documentation written in YUIDoc: https://github.com/ember-learn/ember-cli-addon-docs/blob/master/addon/components/docs-header/component.js#L49

How would this look like with proposed typescript?

I also miss some other features from Ember CLI Addon Docs in this proposal:

• How to mark an argument/yield as internal? E.g. if it should be used for internal composition of components only?
• How to mark an argument/yield as deprecated?

I think support to Ember CLI Addon Docs should be added as a first step to compare the available options. And maybe the scope should be reduced to components bundled with Ember itself. At least as a starting point.

[pzuraq]

I think the goal here is to use standard tooling by default. Ember CLI Addon Docs uses a very bespoke, custom system to get that functionality (I wrote it, am very familiar). It's a massive effort to support, and is quite likely to break in the future as more language and framework features are added.

The idea here is to come from the other angle. If all we had were the standard TS/JS tooling options, what would the standard for documentation look like?

From their, we can build on top of the basic standard, and eventually add back a better representation which is more targeted, like the API documentation in ec-addon-docs.

[gossi]

Exactly as what @pzuraq said. Yet there is a valid point to think about alternatives in comparison to (d).ts:

• JS(doc) - This would be the approach of current ec-addon-docs. Most of the times this is jsdoc with support for ember specific doc-tags (e.g. @argument or @yield). The type support for either of those is pretty much what you choose it to be, hardly consumed by third parties and rendered on ec-addon-docs "as is". I think this approach is limited by technology and subjectively feels very much like free text.

• JSONSchema - There is a way in bending its use to document components. Similar to the approach above it then needs ember specific keywords and tools to understand, postprocess and display that.

• More? - I am running out of options here 😬 If you find another alternative I am happy to hear about.

I can think of a converter/codemod that takes already existing ec-addon-docs jsdocs and port its over to whatever might be at some day the standard.

Form what I think we know now the (d).ts way of doing it is the most practical, beneficial one that covers input and output of components. In terms of scope, arguments might be scoped out (or moved to the referenced issue).

[pzuraq]

It also has other benefits, too. If we lean on TS definitions here, in the future it'll mean that future tooling can take advantage of those types, etc. Eventually when we have typed templates, we'll get even more benefits.

[jelhan]

I agree that using TypeScript has a lot of advantages. I'm not against the proposal. I just think that it needs to provide an upgrade path for addons that are using advanced features like descriptions and marking an argument / yield as private or deprecated.

Haven't much experience with it but maybe it's just about naming TSDoc / TypeDoc as an optional addition if more advanced documentation is needed?

[pzuraq]

I think that the main change here would be to expand the type definitions of @glimmer/component, rather than adopting any documenting conventions or tools directly into core. The tooling solutions behind ec-addon-docs and TS are both too volatile at the moment to maintain directly as a core part of Ember, IMO, but for the TS solution to work we’d need to update the types for components.

Whatever docs solutions are built on top of those could build on that base. If ec-addon-docs adds a documenter that understands TS, that’d be great 👍

[jelhan]

I think that the main change here would be to expand the type definitions of @glimmer/component, rather than adopting any documenting conventions or tools directly into core.

Thanks a lot for the clarification. This wasn't clear to me so far. I think it would be helpful to scope a RFC to adding support for TypeScript documentation but not making any recommendation if it should be preferred over other options. Such a recommendation could be added later in a follow-up RFC as soon as we gathered more experience.