Update API reference descriptions for consistency across components #7071

geospatialem · 2023-05-31T17:37:50Z

Description

Comb through all components and update all API ref descriptions to fit our style guide from #4442, which include:

Use complete sentences with proper grammar, capitalization, and punctuation.
No abbreviations, e.g. use "property" instead of "prop".
Verbs must be in present tense (e.g., "emits" instead of "emitted").
When referring to the component that the property/slot/method/css variable belongs to, call it "the component".
Use the full tag name when referencing other Calcite Components (prefix with calcite-), e.g. calcite-button instead of button.
For plural context, use calcite-buttons instead of calcite-button elements.
Use backticks (`) for the names of slots, events, properties, CSS variables, and component names.
- In line with the JSAPI docs example
- Docs will incorporate styling with afd-calcite-documentation issue #490
Use double quotes (") for the values of properties/attributes and event details.
Only use single quotes (') as apostrophes.
No links or URLs allowed in descriptions. If a link is necessary, a custom JSDoc tag should be added and parsed in the SDK site.
Refrain from using "e.g." or "i.e." references. Leverage "such as" (or similar) where examples are referenced.
Use "Accessible" instead of "Aria" language
Verify slots don't use the text "optional" in their descriptions
Remove optional JSDoc tags for props (?)

Original Issue Description

Our property/slot/method descriptions are all over the place right now. We need to decide on some conventions, and then audit and proofread to make sure they are consistent. Some things to consider:

Should they be sentences with proper case/punctuation/grammar, or should they be more like bullet points?
Which verb tense should we use?
Which quotation marks should be used (single vs double vs tick) in the descriptions? Should different quotation marks be used for different purposes (calcite-xyz vs "value")? e.g. disableCloseOnSelect uses double and overlayPositioning uses single
How should components be named when mentioned in the description? Should they be the full tag name? Should they be in quotes? - here here here here
Should links be allowed in the description? If so, how should they be formatted? e.g. indeterminate, download, value

In addition to the consistency conventions, there is a lot of clean up that needs to happen. For example,

The description does not need to mention the default, since it is specified in the table - here
- This also applies to documentation that is linked out, and contains many properties.
The description does not need to specify that it is read-only, since it displays a chip based on a jsdoc tag here
Product names should be capitalized, e.g. "Calcite UI Icons" vs this

This is not an exhaustive list, but it is a start. If anyone else has something to add please feel free. @geospatialem and I will decide on and document the conventions, and then start updating the jsdoc.

Which Component

All components

Progress checklist

Verified checklist

Resources

No response

The text was updated successfully, but these errors were encountered:

@DitwanP

…ription refs (#8533) **Related Issue:** #7071 ## Summary Updates doc consistency across a-named components defined in the above issue for props, events, methods, and css vars, including: - `action-bar` - `action-group` - `action-pad` - `alert` cc @DitwanP

@DitwanP

…ription refs (#8533) **Related Issue:** #7071 ## Summary Updates doc consistency across a-named components defined in the above issue for props, events, methods, and css vars, including: - `action-bar` - `action-group` - `action-pad` - `alert` cc @DitwanP

… api description refs (#8535) **Related Issue:** #7071 ## Summary Updates doc consistency across t and v-named components defined in the above issue for props, events, methods, and css vars, including: - `tab-nav` - `table` - `tabs` - `tile-select` - `tree` - `value-list`

@geospatialem

**Related Issue:** #7071 ## Summary Updates doc consistency across b and c-named components defined in the above issue for props, events, methods, and css vars, including: - `button` - `block` - `block-section` - `color-picker-hex-input` - `color-picker` - `combobox` cc @geospatialem

@geospatialem

…8540) **Related Issue:** #7071 ## Summary Updates doc consistency across b and c-named components defined in the above issue for props, events, methods, and css vars, including: - `date-picker-day` - `date-picker-month` - `date-picker-month-header` - `dropdown-group` - `dropdown-item` - `filter` - `graph` - `handle` cc @geospatialem

**Related Issue:** #7071 ## Summary Updates doc consistency across m through s-named components defined in the above issue for props, events, methods, and css vars, including: - `meter` - Also includes some inconsistencies in the prop names - `modal` - `navigation-logo` - `navigation-user` - `navigation` - `notice` - `pick-list` - `popover` - `select` - `sheet` - `shell-panel` - `slider` - `split-button`

@geospatialem

**Related Issue:** #7071 ## Summary Updates doc consistency across i and l-named components defined in the above issue for props, events, methods, and css vars, including: - `input-date-picker` - `input-time-zone` - `list-item-group` - `list-item` - `list` cc @geospatialem

github-actions · 2024-01-08T19:12:06Z

Installed and assigned for verification.

geospatialem · 2024-01-09T16:00:00Z

@DitwanP Found a few small additions we could make while verifying some components:

It looks like we could add in backticks to input-time-zone's referenceDate prop, WRT the Date, and backticks and double quotes to "YYYY-MM-DD" and "YYYY-MM-DDTHH:MM:SS.SSSZ".

calcite-design-system/packages/calcite-components/src/components/input-time-zone/input-time-zone.tsx

Line 156 in 72a1ce4

    
              * It can be either a Date instance or a string in ISO format (YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS.SSSZ)

It looks like input-time-zone's events don't have doc yet, maybe we could add some context in for folks?

calcite-design-system/packages/calcite-components/src/components/input-time-zone/input-time-zone.tsx

Lines 214 to 222 in 72a1ce4

    
           @Event({ cancelable: false }) calciteInputTimeZoneBeforeClose: EventEmitter<void>; 
        
           @Event({ cancelable: false }) calciteInputTimeZoneBeforeOpen: EventEmitter<void>; 
        
           @Event({ cancelable: false }) calciteInputTimeZoneChange: EventEmitter<void>; 
        
           @Event({ cancelable: false }) calciteInputTimeZoneClose: EventEmitter<void>; 
        
           @Event({ cancelable: false }) calciteInputTimeZoneOpen: EventEmitter<void>;

Were we also aiming to include other props with multiple selections as part of this effort? It looks like there may be a few remaining items, including:

combobox's selectionDisplay:

calcite-design-system/packages/calcite-components/src/components/combobox/combobox.tsx

Lines 125 to 127 in 72a1ce4

    
              * When `selectionMode` is `"ancestors"` or `"multiple"`, specifies the display of multiple `calcite-combobox-item` selections 
        
              * - `"all"` (displays all selections with individual `calcite-chip`s), `"fit"` (displays individual `calcite-chip`s that scale to the component's size, including a non-closable `calcite-chip`, which provides the number of additional `calcite-combobox-item` selections not visually displayed), or `"single"` (display one `calcite-chip` with the total number of selections). 
        
              */

shell-panel's displayMode:

calcite-design-system/packages/calcite-components/src/components/shell-panel/shell-panel.tsx

Lines 77 to 80 in 72a1ce4

    
             /** 
        
              * Specifies the display mode - `"dock"` (full height, displays adjacent to center content), `"float"` (not full height, content is separated detached from `calcite-action-bar`, displays on top of center content), 
        
              * or `"overlay"` (full height, displays on top of center content). 
        
              */

DitwanP · 2024-01-09T17:48:52Z

Were we also aiming to include other props with multiple selections as part of this effort? It looks like there may be a few remaining items, including:

😱 I thought we got all the selectionMode props. Anything else that needed to be listed out in a similar fashion I was going to make a separate PR for those. At least that was the plan.

I'll get the PR in to address the things you mentioned here.

geospatialem · 2024-01-09T18:15:21Z

😱 I thought we got all the selectionMode props. Anything else that needed to be listed out in a similar fashion I was going to make a separate PR for those. At least that was the plan.

Ah, gotcha. Do we want a separate issue to address those props, or we should work towards addressing them in this issue? I'm good with either approach.

DitwanP · 2024-01-09T18:34:36Z

😱 I thought we got all the selectionMode props. Anything else that needed to be listed out in a similar fashion I was going to make a separate PR for those. At least that was the plan.

Ah, gotcha. Do we want a separate issue to address those props, or we should work towards addressing them in this issue? I'm good with either approach.

I don't have a preference either, I'm fine with leaving this one open and getting a PR added in for those changes, that seems like the simplest route.

**Related Issue:** #7071 ## Summary Updates doc consistency across various components defined in the above issue for props, events, methods, and css vars, including: - `block-section` - `checkbox` - `chip` - `combobox` - `fab` - `input-number` - `input-time-zone` - `radio-button` - `segmented-control` - `shell-panel` - `switch` - `text-area` - `tile-select` - `tree` --------- Co-authored-by: Matt Driscoll <mdriscoll@esri.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

github-actions · 2024-01-10T23:23:40Z

Installed and assigned for verification.

DitwanP · 2024-01-10T23:36:35Z

The only thing of note that I came across when validating was this.

Do we want to remove these parenthesis from navigation-user and reword the sentence?

geospatialem · 2024-01-11T15:50:34Z

Do we want to remove these parenthesis from navigation-user and reword the sentence?

It's also part of avatar's thumbnail prop.

I think the parenthesis help differentiate the focus since its dependent on what the developer is implementing, but if we have a revision in mind - we could change it as well. WDYT?

calcite-design-system/packages/calcite-components/src/components/avatar/avatar.tsx

Lines 22 to 23 in dc5cfb3

    
           /** Specifies the `src` to an image (remember to add a token if the user is private). */ 
        
           @Prop({ reflect: true }) thumbnail: string;

cris6097 · 2024-01-11T16:06:45Z

[celebrate] Cris Ortega reacted to your message:

…

________________________________ From: Kitty Hurley ***@***.***> Sent: Thursday, January 11, 2024 3:51:04 PM To: Esri/calcite-design-system ***@***.***> Cc: Subscribed ***@***.***> Subject: Re: [Esri/calcite-design-system] Update API reference descriptions for consistency across components (Issue #7071) * Do we want to remove these parenthesis from navigation-user [github.com]<https://urldefense.com/v3/__https://github.com/Esri/calcite-design-system/blob/dc5cfb3b1073c18d9036b97647beb308aeddc128/packages/calcite-components/src/components/navigation-user/navigation-user.tsx*L36C1-L37C29__;Iw!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXqDegDLc$> and reword the sentence? It's also part of avatar's thumbnail prop. I think the parenthesis help differentiate the focus since its dependent on what the developer is implementing, but if we have a revision in mind - we could change it as well. WDYT? https://github.com/Esri/calcite-design-system/blob/dc5cfb3b1073c18d9036b97647beb308aeddc128/packages/calcite-components/src/components/avatar/avatar.tsx#L22-L23 [github.com]<https://urldefense.com/v3/__https://github.com/Esri/calcite-design-system/blob/dc5cfb3b1073c18d9036b97647beb308aeddc128/packages/calcite-components/src/components/avatar/avatar.tsx*L22-L23__;Iw!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXmnXRV0v$> — Reply to this email directly, view it on GitHub [github.com]<https://urldefense.com/v3/__https://github.com/Esri/calcite-design-system/issues/7071*issuecomment-1887457716__;Iw!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXvI-KUWY$>, or unsubscribe [github.com]<https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/ABUADLJXHO3A5Y7Z3GOMK6TYOAC6PAVCNFSM6AAAAAAYVZMXRCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBXGQ2TONZRGY__;!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXnFGwJbN$>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

cris6097 · 2024-01-11T16:07:26Z

[0] Cris Ortega reacted to your message:

…

________________________________ From: Kitty Hurley ***@***.***> Sent: Thursday, January 11, 2024 3:51:04 PM To: Esri/calcite-design-system ***@***.***> Cc: Subscribed ***@***.***> Subject: Re: [Esri/calcite-design-system] Update API reference descriptions for consistency across components (Issue #7071) * Do we want to remove these parenthesis from navigation-user [github.com]<https://urldefense.com/v3/__https://github.com/Esri/calcite-design-system/blob/dc5cfb3b1073c18d9036b97647beb308aeddc128/packages/calcite-components/src/components/navigation-user/navigation-user.tsx*L36C1-L37C29__;Iw!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXqDegDLc$> and reword the sentence? It's also part of avatar's thumbnail prop. I think the parenthesis help differentiate the focus since its dependent on what the developer is implementing, but if we have a revision in mind - we could change it as well. WDYT? https://github.com/Esri/calcite-design-system/blob/dc5cfb3b1073c18d9036b97647beb308aeddc128/packages/calcite-components/src/components/avatar/avatar.tsx#L22-L23 [github.com]<https://urldefense.com/v3/__https://github.com/Esri/calcite-design-system/blob/dc5cfb3b1073c18d9036b97647beb308aeddc128/packages/calcite-components/src/components/avatar/avatar.tsx*L22-L23__;Iw!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXmnXRV0v$> — Reply to this email directly, view it on GitHub [github.com]<https://urldefense.com/v3/__https://github.com/Esri/calcite-design-system/issues/7071*issuecomment-1887457716__;Iw!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXvI-KUWY$>, or unsubscribe [github.com]<https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/ABUADLJXHO3A5Y7Z3GOMK6TYOAC6PAVCNFSM6AAAAAAYVZMXRCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBXGQ2TONZRGY__;!!CKZwjTOV!3RuS4meTUDzVCjiZDgrqnVKhLpJdTkZnfKvDXFKrXkL0QjGez1G5pVoXvNfqulNXlG43FwV7boGzXnFGwJbN$>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

DitwanP · 2024-01-11T17:49:56Z

I think the parenthesis help differentiate the focus since its dependent on what the developer is implementing, but if we have a revision in mind - we could change it as well. WDYT?

That makes sense, I think its fine to stay.

DitwanP · 2024-01-11T17:52:50Z

🍡 @geospatialem verified the top half of components, and I verified the bottom half.

geospatialem added this to the 2023 August Priorities milestone May 31, 2023

geospatialem self-assigned this May 31, 2023

geospatialem mentioned this issue May 31, 2023

Define style guide and proof read component API reference #4442

Closed

83 tasks

geospatialem modified the milestones: 2023 August Priorities, 2023 September Priorities - Main release Aug 25, 2023

geospatialem modified the milestones: 2023 September Priorities - Main release, 2023 November Priorities Sep 15, 2023

geospatialem modified the milestones: 2023 November Priorities, 2023 December Priorities Nov 20, 2023

geospatialem modified the milestones: 2023 December Priorities, 2024 January Priorities - Main release Dec 6, 2023

geospatialem assigned DitwanP Dec 13, 2023

geospatialem mentioned this issue Jan 2, 2024

docs(action-bar, action-group, action-pad, alert): consistent api decription refs #8533

Merged

geospatialem added 2 - in development Issues that are actively being worked on. and removed 1 - assigned Issues that are assigned to a sprint and a team member. labels Jan 2, 2024

geospatialem mentioned this issue Jan 2, 2024

feat(handle): add selected property and calciteHandleChange event. #8484

Merged

geospatialem mentioned this issue Jan 2, 2024

docs(tab-nav, table, tabs, tile-select, tree, value-list): consistent api description refs #8535

Merged

This was referenced Jan 2, 2024

docs(b and c components): consistent api description refs #8536

Merged

docs(d, f, g, and h-named components): update api description refs #8540

Merged

geospatialem mentioned this issue Jan 3, 2024

docs: consistent api description refs m thru s-comps #8545

Merged

DitwanP mentioned this issue Jan 3, 2024

docs(various components): consistent api description refs #8550

Merged

DitwanP added 3 - installed Issues that have been merged to master branch and are ready for final confirmation. and removed 2 - in development Issues that are actively being worked on. labels Jan 8, 2024

geospatialem added 2 - in development Issues that are actively being worked on. and removed 3 - installed Issues that have been merged to master branch and are ready for final confirmation. labels Jan 9, 2024

DitwanP mentioned this issue Jan 9, 2024

docs: improve consistency for component prop descriptions #8580

Merged

DitwanP added 3 - installed Issues that have been merged to master branch and are ready for final confirmation. and removed 2 - in development Issues that are actively being worked on. labels Jan 10, 2024

DitwanP closed this as completed Jan 11, 2024

DitwanP added 4 - verified Issues that have been released and confirmed resolved. and removed 3 - installed Issues that have been merged to master branch and are ready for final confirmation. labels Jan 11, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update API reference descriptions for consistency across components #7071

Update API reference descriptions for consistency across components #7071

geospatialem commented May 31, 2023 •

edited by DitwanP

Loading

github-actions bot commented Jan 8, 2024

geospatialem commented Jan 9, 2024 •

edited by DitwanP

Loading

DitwanP commented Jan 9, 2024

geospatialem commented Jan 9, 2024

DitwanP commented Jan 9, 2024

github-actions bot commented Jan 10, 2024

DitwanP commented Jan 10, 2024

geospatialem commented Jan 11, 2024

cris6097 commented Jan 11, 2024 via email

cris6097 commented Jan 11, 2024 via email

DitwanP commented Jan 11, 2024

DitwanP commented Jan 11, 2024

Update API reference descriptions for consistency across components #7071

Update API reference descriptions for consistency across components #7071

Comments

geospatialem commented May 31, 2023 • edited by DitwanP Loading

Description

Original Issue Description

Which Component

Verified checklist

Resources

github-actions bot commented Jan 8, 2024

geospatialem commented Jan 9, 2024 • edited by DitwanP Loading

DitwanP commented Jan 9, 2024

geospatialem commented Jan 9, 2024

DitwanP commented Jan 9, 2024

github-actions bot commented Jan 10, 2024

DitwanP commented Jan 10, 2024

geospatialem commented Jan 11, 2024

cris6097 commented Jan 11, 2024 via email

cris6097 commented Jan 11, 2024 via email

DitwanP commented Jan 11, 2024

DitwanP commented Jan 11, 2024

geospatialem commented May 31, 2023 •

edited by DitwanP

Loading

geospatialem commented Jan 9, 2024 •

edited by DitwanP

Loading