Status: DRAFTED

Champion: Nathan McWilliams (@mysticflute) | Lightning Tooling Team

Revision: latest

RFC created: 2020/03/11

Last updated: 2020/05/07

RFC: https://github.com/salesforce/lwc-rfcs/pull/26

Implementation: 228+

This RFC is under review in PR (#26)

Documentation-related Metadata

Summary

Component authors need a way to provide documentation-related metadata - metadata that is specifically useful for documentation purposes and not runtime behavior. This includes information like component categorization and supported Salesforce experiences.

This metadata is comprised of key-value pairs and will be put in the documentation markdown file, docs/module.md.

Basic example

Example documentation markdown file with documentation metadata:

---
category: Navigation
experience: Lightning, Communities, Mobile
---

descriptive documentation...

Motivation

As part of our path towards enabling customers to document their modules, customers need to be able to add documentation-related metadata. This metadata will be useful for tooling and reference materials. For example, component categories and experiences are displayed in the Component Library documentation website and also used for filtering lists. This metadata can also be used for linting in the LSPs.

In addition, for existing Salesforce-authored modules there's a need to put component authors in control of this metadata. Currently a hardcoded list is maintained by a single team which is a roadblock for other teams creating new components or wishing to update the values.

Detailed design

Key-value pairs will be placed as frontmatter (in YAML format) in the module markdown file that lives under __docs__ in the module bundle. For example, this could be the content for input/__docs__/input.md:

---
category: Data Entry
experience: All
---

descriptive documentation...

Recognized Fields

LWC compiler itself will not restrict the set of fields a component author could add to the frontmatter, however only specific fields will be documented as recognized by the Salesforce platform. Unrecognized fields may be present but they will be ignored.

The following keys will be recognized in the frontmatter:

Recognized Categories

The following category values will be documented as recognized by Salesforce:

Recognized Experiences

The following experience values will be documented as recognized by Salesforce:

Parsing

Please note the following implementation is already in place, but is included here for completion. That said, now is a good time to address any concerns before opening up usage on the platform.

The frontmatter will be parsed by the platform compiler using greymatter and included in the documentation section of the compiler output:

export interface PlatformBundleDoc {
    classDescription?: string;
    html?: string;
    metadata?: DocumentationMetadata;
}

export interface DocumentationMetadata {
    [key: string]: any;
}

Field Agnostic

The platform-compiler will be agnostic to the fields and their meanings. Correct YAML grammar will be enforced, but downstream code such as the Component Library will be responsible for determining which fields are applicable and which values may need further processing, such as splitting the experience field on commas.

The benefit of this approach is flexibility and reduced overhead on the platform-compiler. Also consumption of these values is not limited to Salesforce technologies such as the Component Library, so a whitelist at the compiler level could prove too restrictive.

The downside is that content-based errors (such as using an unrecognized category) won’t be caught until further downstream. This can be mitigated somewhat with linting.

Another downside of being agnostic (and not validating the allowed fields) is that the future introduction of new fields may “conflict” with existing fields. That is, a component author could add any arbitrary field, even if Salesforce does not use or display that field, which could conflict with Salesforce’s use of that field name later. This should be rare, however, and since this data does not affect runtime behavior the impact is minimal. Customers will have time to make any necessary updates at their convenience.

Alternatives

Rejected Fields

Adoption strategy

Currently we maintain a hardcoded list of categories and experiences for lightning base components and other exposed components. This information will be transferred to the individual component bundles and be maintained by the component owners going forward.

This is also part of the effort to enable platform developers to create documentation for their components, in which we should allow them to provide the same categorization information as we do for Salesforce components.

How we teach this

In general, every developer creating public components will need to make sure of the following:

  1. The component has a quality markdown file.
  2. The component specifies necessary documentation metadata (experience, category, etc...)
  3. The component has one or more examples.
  4. The component has JSDoc on public members.

Unresolved questions

  1. Is there an existing way deprecation is already specified? Does it make more sense to use the @deprecated tag from JSDoc? Also, should we have another field for the replacement component?
  2. Is there an issue with saving files under __docs__ in the platform?
  3. Should the compiler validate expected values? If not then how will customers discover if they are using a valid value or not? Tooling can be of assistance here.
undefined