RFC: Documentation-related Metadata #26
Conversation
|
@mysticflute gave you access |
mysticflute
requested review from
KrisGraySFDC,
pmdartus,
caridy,
diervo and
apapko
|
|
||
| The following keys will be recognized in the frontmatter: | ||
|
|
||
| * __category__ `string` \ |
There was a problem hiding this comment.
What is the default value if any? What happens if no category is specified, is it considered as unclassified?
There was a problem hiding this comment.
It would be up to the consumer to decide which text to use to describe a lack of categorization. None of these fields would be considered required from the compiler standpoint.
|
|
||
| * __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. | ||
| * __experience__ `string[]` \ |
There was a problem hiding this comment.
What is the default value?
Is there a way to a module is portable and available in all the experience out of the box? Listing all the experiences is not an option here, since we might add new experiences in the futures and modules hardcoding all the experiences will need to be updated to add the new experience to the list.
There was a problem hiding this comment.
yes that's a good point. An 'All' experience is reasonable. The risk is that people will tend to use that without testing their components in the experience, or new experiences may be added that some existing components don't support.
| * __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. |
There was a problem hiding this comment.
In order to implement component grouping, we will need more information than just a boolean.
Have you thought of having a property called validParentComponent that would reference in which context this component 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 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` \ |
There was a problem hiding this comment.
Is there an existing way deprecation is already specified?
I am not aware of a standard way to mark a component as deprecated.
Does it make more sense to use the
@deprecatedtag from JSDoc?
It makes sense to keep the @deprecated notation in JSDoc. Even if a module/component is not deprecated, some of their methods and properties might be.
Also, should we have another field for the replacement component?
It is not uncommon that a deprecated module doesn't have a 1-1 replacement. Deprecated requires most of the time some free form text to indicate how to migrate, we can ask for deprecated modules to add a banner in the documentation explaining the migration strategy. We can also add another property called deprecationMessage to have a standard way to surface in the component library and the different tools.
There was a problem hiding this comment.
I like the idea of deprecationMessage, as that can be used easier in tools like the editor LSPs. For more complicated scenarios I agree this could be supplemented with more information in the documentation itself.
When I talked with Alex and Ravi it came up that a deprecation flag might be added to the .js-meta.xml file. I'm not sure if it belongs there, but I agree the @deprecated tag works better than in the doc metadata, so how we flag deprecation can be a separate discussion.
Co-authored-by: Ravi Jayaramappa <ravi.jayaramappa@salesforce.com>
Co-authored-by: Pierre-Marie Dartus <dartus.pierremarie@gmail.com>
Co-authored-by: Pierre-Marie Dartus <dartus.pierremarie@gmail.com>
Co-authored-by: Pierre-Marie Dartus <dartus.pierremarie@gmail.com>
Co-authored-by: Ravi Jayaramappa <ravi.jayaramappa@salesforce.com>
https://rfcs.lwc.dev/rfcs/lwc/0000-documentation-related-metadata