From 400afb31d1acf94520a50c64e75a2c1d585638b4 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Tue, 10 Mar 2020 16:54:30 -0400 Subject: [PATCH 01/16] initial content --- text/0000-documentation-related-metadata.md | 139 ++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 text/0000-documentation-related-metadata.md diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md new file mode 100644 index 00000000..cfce2b91 --- /dev/null +++ b/text/0000-documentation-related-metadata.md @@ -0,0 +1,139 @@ +--- +title: Documentation-related Metadata +status: DRAFTED +created_at: 2020-03-10 +updated_at: 2020-03-10 +pr: (leave this empty until the PR is created) +--- + +# Documentation-related Metadata + +## Summary + +Component authors need a way to provide documentation-related metadata— metadata that is only useful for documentation purposes and not runtime behavior. This is information such as component categorization, and it usually takes the format of key-value pairs. + +## Basic example + +```markdown +--- +category: Data Entry +experience: Lightning +--- + +descriptive documentation... +``` + +## Motivation + +As part of our path towards allowing customers to add documentation for their modules, there's a need for customers to be able to add documentation-related metadata that will be useful for tooling and documentation purposes. For example, component categories and experiences are displayed in the Component Library documentation website and used for filtering. + +In addition, for Salesforce-authored modules there's a need to put component authors in control of this metadata. Currently a hardcoded list of metadata is maintained for a hardcoded list of components, which is a roadblock for teams creating new components or wishing to update the values. + +There needs to be a standard way to specify certain documentation-related key-value pairs that balances component-author ownership with + +## Detailed design + +Key-value pairs will be placed as [frontmatter](https://github.com/jonschlinkert/gray-matter#what-does-this-do) (in YAML format) in the module markdown file that lives under __docs__. For example, this could be the content for `input/__docs__/input.md`: + +```markdown +--- +category: Data Entry +experience: Lightning +--- + +descriptive documentation... +``` + +### Recognized Fields + +The following information can be specified in the frontmatter: + +* __category__ `string` + The main category for the component. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. +* __experience__ `string[]` + One or more Salesforce experiences that the component works in. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. +* __isSubComponent__ `boolean` + This denotes that the component is only intended for use inside of another component, for example lightning-breadcrumb is only used inside of lightning-breadcrumbs. The Component Library may use this information to automatically cross-link pages or provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view). +* __deprecated__ `boolean` + This does not impact runtime behavior at all. The Component Library may use this information to provide filtering capabilities or special UX treatment. Is there another value that we can use for this already (in js-meta.xml)? Does it make more sense to use the @deprecated tag from JSDoc? Also, should we have another field for the replacement component? + +### Parsing + +Please note the following implementation is already in place, but is included here for completion. Also 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](https://github.com/jonschlinkert/gray-matter) and included in the documentation section of the compiler output: + +```typescript +export interface PlatformBundleDoc { + classDescription?: string; + html?: string; + *metadata?: DocumentationMetadata;* +} + +export interface DocumentationMetadata { + [key: string]: any; +} +``` + +In Aura this information will be placed on the ModuleDefinition as a `Map`. + +#### Value 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. + +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 whitelisting/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. + +## Drawbacks + + +Why should we *not* do this? Please consider: + +- implementation cost, both in term of code size and complexity +- whether the proposed feature can be implemented in user space +- the impact on teaching people Lightning Web Components +- integration of this feature with other existing and planned features +- cost of migrating existing Lightning Web Components applications (is it a breaking change?) + +There are tradeoffs to choosing any path. Attempt to identify them here. + +## Alternatives + +- While this information could continue to live apart from the module bundle as it is today, it is not a sustainable approach and does not work for the platform. + +### Rejected Fields + +* __image__ + The Component Library uses images for components on the home page. The map from component to image is currently hardcoded. This field is rejected because there's a good chance these images are going away and they pose many complications. + +## Adoption strategy + +Currently we maintain a hardcoded list of categories and experiences for lightning base components. This information will be transferred to the individual source files 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. + +Separate RFCs will be filed for opening up other related documentation features to the platform such as examples, and supporting events, non-component modules, and more. +What names and terminology work best for these concepts and why? How is this +idea best presented? As a continuation of existing Lightning Web Components patterns? + +Would the acceptance of this proposal mean the Lightning Web Components documentation must be +re-organized or altered? Does it change how Lightning Web Components is taught to new developers +at any level? + +How should this feature be taught to existing Lightning Web Components developers? + +# Unresolved questions + +As mentioned above, is this the correct format to signify deprecation? \ No newline at end of file From facaf367bd0a50e125ac891805bf0cb17e551cf7 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Tue, 10 Mar 2020 17:40:15 -0400 Subject: [PATCH 02/16] updates --- text/0000-documentation-related-metadata.md | 84 ++++++++++++--------- 1 file changed, 50 insertions(+), 34 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index cfce2b91..89cd068a 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -10,9 +10,10 @@ pr: (leave this empty until the PR is created) ## Summary -Component authors need a way to provide documentation-related metadata— metadata that is only useful for documentation purposes and not runtime behavior. This is information such as component categorization, and it usually takes the format of key-value pairs. +Component authors need a way to provide documentation-related metadata-- metadata that is only useful for documentation purposes and not runtime behavior. This includes information like component categorization. This metadata is usually comprised of key-value pairs and will be put in the documentation markdown file, `docs/module.md`. ## Basic example +Example documentation markdown file: ```markdown --- @@ -25,15 +26,15 @@ descriptive documentation... ## Motivation -As part of our path towards allowing customers to add documentation for their modules, there's a need for customers to be able to add documentation-related metadata that will be useful for tooling and documentation purposes. For example, component categories and experiences are displayed in the Component Library documentation website and used for filtering. +As part of our path towards allowing customers to add documentation for their modules, there's a need for customers to be able to add documentation-related metadata. This metadata will be useful for tooling and documentation purposes. For example, component categories and experiences are displayed in the Component Library documentation website and used for filtering. In addition, for Salesforce-authored modules there's a need to put component authors in control of this metadata. Currently a hardcoded list of metadata is maintained for a hardcoded list of components, which is a roadblock for teams creating new components or wishing to update the values. -There needs to be a standard way to specify certain documentation-related key-value pairs that balances component-author ownership with +There needs to be a standard way to specify certain documentation-related key-value pairs that balances component-author ownership with a standard representation. ## Detailed design -Key-value pairs will be placed as [frontmatter](https://github.com/jonschlinkert/gray-matter#what-does-this-do) (in YAML format) in the module markdown file that lives under __docs__. For example, this could be the content for `input/__docs__/input.md`: +Key-value pairs will be placed as [frontmatter](https://github.com/jonschlinkert/gray-matter#what-does-this-do) (in YAML format) in the module markdown file that lives under `__docs__`. For example, this could be the content for `input/__docs__/input.md`: ```markdown --- @@ -48,18 +49,51 @@ descriptive documentation... The following information can be specified in the frontmatter: -* __category__ `string` +* __category__ `string` \ The main category for the component. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. -* __experience__ `string[]` +* __experience__ `string[]` \ One or more Salesforce experiences that the component works in. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. -* __isSubComponent__ `boolean` +* __isSubComponent__ `boolean` \ This denotes that the component is only intended for use inside of another component, for example lightning-breadcrumb is only used inside of lightning-breadcrumbs. The Component Library may use this information to automatically cross-link pages or provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view). -* __deprecated__ `boolean` +* __deprecated__ `boolean` \ This does not impact runtime behavior at all. The Component Library may use this information to provide filtering capabilities or special UX treatment. Is there another value that we can use for this already (in js-meta.xml)? Does it make more sense to use the @deprecated tag from JSDoc? Also, should we have another field for the replacement component? +#### Recognized Categories + +The following category values will be documented as recognized by Salesforce: + +* Analytics +* API +* Buttons +* Data Entry +* Displaying Data +* Feed +* Files +* Forms +* Layout +* Logic +* Messaging +* Navigation +* Process/Workflow +* Service +* Visual + +#### Recognized Experiences + +The following experience values will be documented as recognized by Salesforce: + +* All +* Communities +* Lightning +* Mobile +* Lightning Out +* Standalone +* Snapins + + ### Parsing -Please note the following implementation is already in place, but is included here for completion. Also now is a good time to address any concerns before opening up usage on the platform. +_Please note the following implementation is already in place, but is included here for completion. Also 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](https://github.com/jonschlinkert/gray-matter) and included in the documentation section of the compiler output: @@ -67,7 +101,7 @@ The frontmatter will be parsed by the platform compiler using [greymatter](https export interface PlatformBundleDoc { classDescription?: string; html?: string; - *metadata?: DocumentationMetadata;* + metadata?: DocumentationMetadata; } export interface DocumentationMetadata { @@ -89,25 +123,15 @@ Another downside of being agnostic (and not whitelisting/validating the allowed ## Drawbacks - -Why should we *not* do this? Please consider: - -- implementation cost, both in term of code size and complexity -- whether the proposed feature can be implemented in user space -- the impact on teaching people Lightning Web Components -- integration of this feature with other existing and planned features -- cost of migrating existing Lightning Web Components applications (is it a breaking change?) - -There are tradeoffs to choosing any path. Attempt to identify them here. - ## Alternatives -- While this information could continue to live apart from the module bundle as it is today, it is not a sustainable approach and does not work for the platform. +- While this information could continue to live apart from the module bundle as it is today, that's not a sustainable approach and does not work for the platform. +- This data could be written as custom JSDoc tags in the js file, but those tags would be non-standard. This information feels better suited to the documentation file. ### Rejected Fields -* __image__ - The Component Library uses images for components on the home page. The map from component to image is currently hardcoded. This field is rejected because there's a good chance these images are going away and they pose many complications. +* __image__ \ + The Component Library uses images for components on the home page. The map from component to image is currently hardcoded. If we want to allow the platform to specify similar images then a field here is one solution, but it poses many complications for the implementation details. Also such images are of limited use in other contexts outside of the Component Library, which may not always use such images even itself. ## Adoption strategy @@ -124,16 +148,8 @@ In general, every developer creating public components will need to make sure of 3. The component has one or more examples. 4. The component has JSDoc on public members. -Separate RFCs will be filed for opening up other related documentation features to the platform such as examples, and supporting events, non-component modules, and more. -What names and terminology work best for these concepts and why? How is this -idea best presented? As a continuation of existing Lightning Web Components patterns? - -Would the acceptance of this proposal mean the Lightning Web Components documentation must be -re-organized or altered? Does it change how Lightning Web Components is taught to new developers -at any level? - -How should this feature be taught to existing Lightning Web Components developers? +Separate RFCs will be filed for opening up other related documentation features to the platform such as examples, events, non-component modules, and more. # Unresolved questions -As mentioned above, is this the correct format to signify deprecation? \ No newline at end of file +As mentioned above, is this really the correct format to signify deprecation? \ No newline at end of file From 5249c252d1727d635392c473f91062fbdc0d3106 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Tue, 10 Mar 2020 19:00:59 -0400 Subject: [PATCH 03/16] updates --- text/0000-documentation-related-metadata.md | 36 +++++++++++---------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 89cd068a..9a1314a8 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -10,15 +10,17 @@ pr: (leave this empty until the PR is created) ## Summary -Component authors need a way to provide documentation-related metadata-- metadata that is only useful for documentation purposes and not runtime behavior. This includes information like component categorization. This metadata is usually comprised of key-value pairs and will be put in the documentation markdown file, `docs/module.md`. +Component authors need a way to provide documentation-related metadata-- metadata that is only useful for documentation purposes and not runtime behavior. This includes information like component categorization and supported Salesforce experiences. + +This metadata is usually comprised of key-value pairs and will be put in the documentation markdown file, `docs/module.md`. ## Basic example -Example documentation markdown file: +Example documentation markdown file with documentation metadata: ```markdown --- -category: Data Entry -experience: Lightning +category: Navigation +experience: Lightning, Communities, Mobile --- descriptive documentation... @@ -26,11 +28,9 @@ descriptive documentation... ## Motivation -As part of our path towards allowing customers to add documentation for their modules, there's a need for customers to be able to add documentation-related metadata. This metadata will be useful for tooling and documentation purposes. For example, component categories and experiences are displayed in the Component Library documentation website and used for filtering. +As part of our path towards allowing customers to add documentation for their modules, there's a need for customers to be able to add documentation-related metadata. This metadata will be useful for tooling and documentation purposes. For example, component categories and experiences are displayed in the Component Library documentation website and used for filtering. This metadata could also be used for linting in the LSPs. -In addition, for Salesforce-authored modules there's a need to put component authors in control of this metadata. Currently a hardcoded list of metadata is maintained for a hardcoded list of components, which is a roadblock for teams creating new components or wishing to update the values. - -There needs to be a standard way to specify certain documentation-related key-value pairs that balances component-author ownership with a standard representation. +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 which is a roadblock for teams creating new components or wishing to update the values. ## Detailed design @@ -39,7 +39,7 @@ Key-value pairs will be placed as [frontmatter](https://github.com/jonschlinkert ```markdown --- category: Data Entry -experience: Lightning +experience: All --- descriptive documentation... @@ -47,16 +47,18 @@ descriptive documentation... ### Recognized Fields -The following information can be specified in the frontmatter: +LWC 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: * __category__ `string` \ - The main category for the component. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. + The main category for the module. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. * __experience__ `string[]` \ - One or more Salesforce experiences that the component works in. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. + One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. * __isSubComponent__ `boolean` \ - This denotes that the component is only intended for use inside of another component, for example lightning-breadcrumb is only used inside of lightning-breadcrumbs. The Component Library may use this information to automatically cross-link pages or provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view). + This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information to automatically cross-link pages or provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view) and this information could be used for linting. * __deprecated__ `boolean` \ - This does not impact runtime behavior at all. The Component Library may use this information to provide filtering capabilities or special UX treatment. Is there another value that we can use for this already (in js-meta.xml)? Does it make more sense to use the @deprecated tag from JSDoc? Also, should we have another field for the replacement component? + This does not impact runtime behavior. The Component Library may use this information to provide filtering capabilities or special UX treatment. 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? #### Recognized Categories @@ -93,7 +95,7 @@ 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. Also now is a good time to address any concerns before opening up usage on the platform._ +_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](https://github.com/jonschlinkert/gray-matter) and included in the documentation section of the compiler output: @@ -115,11 +117,11 @@ In Aura this information will be placed on the ModuleDefinition as a `Map Date: Wed, 11 Mar 2020 13:05:52 -0400 Subject: [PATCH 04/16] updates --- text/0000-documentation-related-metadata.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 9a1314a8..18a437e7 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -92,7 +92,6 @@ The following experience values will be documented as recognized by Salesforce: * Standalone * Snapins - ### 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._ @@ -113,7 +112,7 @@ export interface DocumentationMetadata { In Aura this information will be placed on the ModuleDefinition as a `Map`. -#### Value Agnostic +#### 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. From cbd40e8261e21b8bd71eb8c1ec986725819c4abd Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Wed, 11 Mar 2020 13:43:23 -0400 Subject: [PATCH 05/16] updates --- text/0000-documentation-related-metadata.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 18a437e7..2557ef6a 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -10,9 +10,9 @@ pr: (leave this empty until the PR is created) ## Summary -Component authors need a way to provide documentation-related metadata-- metadata that is only useful for documentation purposes and not runtime behavior. This includes information like component categorization and supported Salesforce experiences. +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 usually comprised of key-value pairs and will be put in the documentation markdown file, `docs/module.md`. +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: @@ -28,13 +28,13 @@ descriptive documentation... ## Motivation -As part of our path towards allowing customers to add documentation for their modules, there's a need for customers to be able to add documentation-related metadata. This metadata will be useful for tooling and documentation purposes. For example, component categories and experiences are displayed in the Component Library documentation website and used for filtering. This metadata could also be used for linting in the LSPs. +As part of our path towards allowing customers to add documentation for 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 which is a roadblock for teams creating new components or wishing to update the values. +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](https://github.com/jonschlinkert/gray-matter#what-does-this-do) (in YAML format) in the module markdown file that lives under `__docs__`. For example, this could be the content for `input/__docs__/input.md`: +Key-value pairs will be placed as [frontmatter](https://github.com/jonschlinkert/gray-matter#what-does-this-do) (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`: ```markdown --- @@ -58,7 +58,7 @@ The following keys will be recognized in the frontmatter: * __isSubComponent__ `boolean` \ This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information to automatically cross-link pages or provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view) and this information could be used for linting. * __deprecated__ `boolean` \ - This does not impact runtime behavior. The Component Library may use this information to provide filtering capabilities or special UX treatment. 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? + This does not impact runtime behavior. The Component Library may use this information to provide filtering capabilities or special UX treatment. 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? #### Recognized Categories @@ -110,7 +110,7 @@ export interface DocumentationMetadata { } ``` -In Aura this information will be placed on the ModuleDefinition as a `Map`. +In Aura this information will be placed on the ModuleDefinition as a `Map`. #### Field Agnostic @@ -122,8 +122,6 @@ The downside is that content-based errors (such as using an unrecognized categor 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. -## Drawbacks - ## Alternatives - While this information could continue to live apart from the module bundle as it is today, that's not a sustainable approach and does not work for the platform. @@ -136,7 +134,7 @@ Another downside of being agnostic (and not validating the allowed fields) is th ## Adoption strategy -Currently we maintain a hardcoded list of categories and experiences for lightning base components. This information will be transferred to the individual source files and be maintained by the component owners going forward. +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. From 3f5db7ebec2168675f397eb4c5e6693fec7bc180 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Wed, 11 Mar 2020 13:53:15 -0400 Subject: [PATCH 06/16] updates --- text/0000-documentation-related-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 2557ef6a..6f15e03e 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -28,7 +28,7 @@ descriptive documentation... ## Motivation -As part of our path towards allowing customers to add documentation for 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. +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. From 4b70dc7841914d406e45634ec32cdc33ddb2dd35 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Wed, 11 Mar 2020 17:02:00 -0400 Subject: [PATCH 07/16] fix metadata --- text/0000-documentation-related-metadata.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 6f15e03e..299d0f6b 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -1,9 +1,11 @@ --- title: Documentation-related Metadata status: DRAFTED -created_at: 2020-03-10 -updated_at: 2020-03-10 -pr: (leave this empty until the PR is created) +created_at: 2020-03-11 +updated_at: 2020-03-11 +rfc: https://github.com/salesforce/lwc-rfcs/pull/26 +champion: Nathan McWilliams (@mysticflute) | Lightning Tooling Team +implementation: 226-228 --- # Documentation-related Metadata From 517d53035d5b9350b7c4ae455d12d7ed10606f66 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Wed, 11 Mar 2020 17:40:49 -0400 Subject: [PATCH 08/16] updates --- text/0000-documentation-related-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 299d0f6b..3d4e778e 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -58,7 +58,7 @@ The following keys will be recognized in the frontmatter: * __experience__ `string[]` \ One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. * __isSubComponent__ `boolean` \ - This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information to automatically cross-link pages or provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view) and this information could be used for linting. + This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information for filtering options, to automatically cross-link pages, or to provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view). Also this information could be used for linting. * __deprecated__ `boolean` \ This does not impact runtime behavior. The Component Library may use this information to provide filtering capabilities or special UX treatment. 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? From ab53e6657fca99b4bec661de4c59219001a5e2d0 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 18:36:27 -0400 Subject: [PATCH 09/16] Update text/0000-documentation-related-metadata.md Co-authored-by: Ravi Jayaramappa --- text/0000-documentation-related-metadata.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 3d4e778e..069d4af4 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -114,6 +114,7 @@ export interface DocumentationMetadata { In Aura this information will be placed on the ModuleDefinition as a `Map`. + #### 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. @@ -153,4 +154,4 @@ Separate RFCs will be filed for opening up other related documentation features # Unresolved questions -As mentioned above, is this really the correct format to signify deprecation? \ No newline at end of file +As mentioned above, is this really the correct format to signify deprecation? From 30e3ca8d2901b3db13915ec916f74a0a57bc1593 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 18:36:39 -0400 Subject: [PATCH 10/16] Update text/0000-documentation-related-metadata.md Co-authored-by: Pierre-Marie Dartus --- text/0000-documentation-related-metadata.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 069d4af4..34e0ba99 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -12,7 +12,8 @@ implementation: 226-228 ## 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. +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`. From bd7db72cff256bc4a0e8f142c078a89bf3c59f7a Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 18:36:48 -0400 Subject: [PATCH 11/16] Update text/0000-documentation-related-metadata.md Co-authored-by: Pierre-Marie Dartus --- text/0000-documentation-related-metadata.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 34e0ba99..e1098138 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -50,7 +50,8 @@ descriptive documentation... ### Recognized Fields -LWC 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. +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: From 3d3db60d21366b67e441ca13cd8f6307411f9df3 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 18:37:10 -0400 Subject: [PATCH 12/16] Update text/0000-documentation-related-metadata.md Co-authored-by: Pierre-Marie Dartus --- text/0000-documentation-related-metadata.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index e1098138..17a3d900 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -60,7 +60,8 @@ The following keys will be recognized in the frontmatter: * __experience__ `string[]` \ One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. * __isSubComponent__ `boolean` \ - This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information for filtering options, to automatically cross-link pages, or to provide [component grouping](https://gus.lightning.force.com/lightning/r/a07B0000006HrUNIA0/view). Also this information could be used for linting. + This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information for filtering options, to automatically cross-link pages, or to provide component grouping. Also this information could be used for linting. + * __deprecated__ `boolean` \ This does not impact runtime behavior. The Component Library may use this information to provide filtering capabilities or special UX treatment. 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? From 6e299d716dae3aad785a97fd0f28d2bcb3d290e7 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 18:38:44 -0400 Subject: [PATCH 13/16] Update text/0000-documentation-related-metadata.md Co-authored-by: Ravi Jayaramappa --- text/0000-documentation-related-metadata.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 17a3d900..1b8d3e07 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -56,7 +56,9 @@ LWC compiler itself will not restrict the set of fields a component author could The following keys will be recognized in the frontmatter: * __category__ `string` \ - The main category for the module. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. + The main category for the module. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library][component-library] for other ways this information can be used. + +[component-library]: https://developer.salesforce.com/docs/component-library/overview/components * __experience__ `string[]` \ One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. * __isSubComponent__ `boolean` \ From b087168cb9fe6c678a594dd9d93cf7dbcd143b33 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 19:00:53 -0400 Subject: [PATCH 14/16] review feedback --- text/0000-documentation-related-metadata.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 1b8d3e07..8d1c6d1c 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -117,9 +117,6 @@ export interface DocumentationMetadata { } ``` -In Aura this information will be placed on the ModuleDefinition as a `Map`. - - #### 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. From 78ef1194850c9072077ea3941a342b6eaab30dfe Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 19:12:49 -0400 Subject: [PATCH 15/16] updates from review feedback --- text/0000-documentation-related-metadata.md | 22 +++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 8d1c6d1c..9b600a7a 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -2,10 +2,10 @@ title: Documentation-related Metadata status: DRAFTED created_at: 2020-03-11 -updated_at: 2020-03-11 +updated_at: 2020-05-07 rfc: https://github.com/salesforce/lwc-rfcs/pull/26 champion: Nathan McWilliams (@mysticflute) | Lightning Tooling Team -implementation: 226-228 +implementation: 228+ --- # Documentation-related Metadata @@ -58,15 +58,12 @@ The following keys will be recognized in the frontmatter: * __category__ `string` \ The main category for the module. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library][component-library] for other ways this information can be used. -[component-library]: https://developer.salesforce.com/docs/component-library/overview/components * __experience__ `string[]` \ - One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for other ways this information can be used. + One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library][component-library] for other ways this information can be used. + * __isSubComponent__ `boolean` \ This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information for filtering options, to automatically cross-link pages, or to provide component grouping. Also this information could be used for linting. -* __deprecated__ `boolean` \ - This does not impact runtime behavior. The Component Library may use this information to provide filtering capabilities or special UX treatment. 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? - #### Recognized Categories The following category values will be documented as recognized by Salesforce: @@ -137,6 +134,9 @@ Another downside of being agnostic (and not validating the allowed fields) is th * __image__ \ The Component Library uses images for components on the home page. The map from component to image is currently hardcoded. If we want to allow the platform to specify similar images then a field here is one solution, but it poses many complications for the implementation details. Also such images are of limited use in other contexts outside of the Component Library, which may not always use such images even itself. +* __deprecated__ `boolean` \ + This does not impact runtime behavior. The Component Library may use this information to provide filtering capabilities or special UX treatment. + ## 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. @@ -152,8 +152,10 @@ In general, every developer creating public components will need to make sure of 3. The component has one or more examples. 4. The component has JSDoc on public members. -Separate RFCs will be filed for opening up other related documentation features to the platform such as examples, events, non-component modules, and more. - # Unresolved questions -As mentioned above, is this really the correct format to signify deprecation? +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. + + From 300b4cf44dccf60da0b4768e1964f8bb93428512 Mon Sep 17 00:00:00 2001 From: Nathan McWilliams Date: Thu, 7 May 2020 19:18:09 -0400 Subject: [PATCH 16/16] formatting --- text/0000-documentation-related-metadata.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-documentation-related-metadata.md b/text/0000-documentation-related-metadata.md index 9b600a7a..f8da1e0c 100644 --- a/text/0000-documentation-related-metadata.md +++ b/text/0000-documentation-related-metadata.md @@ -56,10 +56,10 @@ LWC compiler itself will not restrict the set of fields a component author could The following keys will be recognized in the frontmatter: * __category__ `string` \ - The main category for the module. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library][component-library] for other ways this information can be used. + The main category for the module. Only one may be specified. Salesforce will maintain a list of recognized categories in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library][1] for other ways this information can be used. * __experience__ `string[]` \ - One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library][component-library] for other ways this information can be used. + One or more Salesforce experiences that the module works in. Salesforce will maintain a list of recognized experiences in public documentation and the VS Code extension for code completion/linting. For applications like the Component Library, values that match the whitelist will be displayed on the component’s reference page. Also see the filters on the homepage of the [Component Library][1] for other ways this information can be used. * __isSubComponent__ `boolean` \ This denotes that the component is only intended for use inside of another component, for example `lightning-breadcrumb` is only used inside of `lightning-breadcrumbs`. The Component Library may use this information for filtering options, to automatically cross-link pages, or to provide component grouping. Also this information could be used for linting. @@ -158,4 +158,4 @@ In general, every developer creating public components will need to make sure of 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. - +[1]: https://developer.salesforce.com/docs/component-library/overview/components