docs: Clean up public API descriptions across components - #2303
Merged
Conversation
damyanpetev
added
documentation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR performs a documentation-only cleanup pass across component JSDoc and generated Storybook metadata so that public API descriptions read correctly in custom-elements.json, Storybook docs, and downstream wrapper docs (Angular/React/Blazor).
Changes:
- Refines component/member/event/slot/csspart descriptions (typos/grammar, factual corrections, and removing tag names from prose).
- Adds missing or improved public API documentation (e.g., new component summaries, added
@returnswhere applicable). - Updates contributor skills/checklists to prevent future doc regressions and generated-story drift.
Reviewed changes
Copilot reviewed 94 out of 94 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| stories/tooltip.stories.ts | Storybook argTypes/docs description wording cleanup |
| stories/textarea.stories.ts | Storybook argTypes/docs description wording cleanup |
| stories/tabs.stories.ts | Storybook component description wording cleanup |
| stories/switch.stories.ts | Storybook argTypes description wording cleanup |
| stories/splitter.stories.ts | Storybook component description wording cleanup |
| stories/slider.stories.ts | Storybook argTypes description wording cleanup |
| stories/select.stories.ts | Storybook argTypes/docs description wording cleanup |
| stories/ripple.stories.ts | Storybook component description wording cleanup |
| stories/rating.stories.ts | Storybook argTypes/docs description wording cleanup |
| stories/radio.stories.ts | Adds missing story component description + wording cleanup |
| stories/radio-group.stories.ts | Storybook docs + argTypes wording cleanup |
| stories/nav-drawer.stories.ts | Storybook argTypes/docs wording cleanup |
| stories/mask-input.stories.ts | Storybook argTypes/docs wording cleanup |
| stories/input.stories.ts | Adds missing story component description + argTypes wording cleanup |
| stories/file-input.stories.ts | Storybook argTypes/docs wording cleanup |
| stories/dropdown.stories.ts | Storybook component description wording cleanup |
| stories/divider.stories.ts | Storybook component description wording cleanup |
| stories/date-time-input.stories.ts | Storybook argTypes wording cleanup |
| stories/date-range-picker.stories.ts | Storybook component + argTypes wording cleanup |
| stories/date-picker.stories.ts | Story rename alignment + regenerated metadata/argTypes updates |
| stories/combo.stories.ts | Storybook argTypes wording cleanup |
| stories/checkbox.stories.ts | Storybook argTypes wording cleanup |
| stories/carousel.stories.ts | Storybook component/argTypes wording cleanup |
| stories/calendar.stories.ts | Storybook argTypes wording correction (hideOutsideDays) |
| stories/button-group.stories.ts | Storybook component description wording cleanup |
| src/extras/chat-markdown-renderer.ts | JSDoc description wording cleanup |
| src/components/tooltip/tooltip.ts | JSDoc description wording cleanup |
| src/components/tile-manager/tile.ts | JSDoc wording + typo fix |
| src/components/tile-manager/tile-manager.ts | Slot description wording cleanup |
| src/components/textarea/textarea.ts | JSDoc and csspart descriptions wording cleanup |
| src/components/tabs/tabs.ts | JSDoc description wording cleanup |
| src/components/tabs/tab.ts | JSDoc description wording cleanup |
| src/components/stepper/stepper.ts | JSDoc description wording cleanup |
| src/components/stepper/step.ts | JSDoc description wording cleanup |
| src/components/splitter/splitter.ts | JSDoc component summary wording cleanup |
| src/components/select/select.ts | JSDoc csspart + property description wording cleanup |
| src/components/select/select-item.ts | JSDoc csspart wording cleanup |
| src/components/select/select-header.ts | JSDoc description wording cleanup |
| src/components/select/select-group.ts | JSDoc layout + wording cleanup |
| src/components/ripple/ripple.ts | JSDoc grammar fix |
| src/components/rating/rating.ts | Slot + property description wording cleanup |
| src/components/rating/rating-symbol.ts | JSDoc description wording cleanup |
| src/components/radio/radio.ts | Adds missing component summary + wording fixes |
| src/components/radio-group/radio-group.ts | JSDoc description wording cleanup |
| src/components/progress/linear-progress.ts | JSDoc csspart wording cleanup |
| src/components/progress/circular-progress.ts | JSDoc slot/csspart wording cleanup |
| src/components/progress/circular-gradient.ts | JSDoc wording/clarity cleanup |
| src/components/nav-drawer/nav-drawer.ts | JSDoc wording cleanup |
| src/components/nav-drawer/nav-drawer-item.ts | JSDoc wording correction (item vs drawer) |
| src/components/nav-drawer/nav-drawer-header-item.ts | JSDoc description wording cleanup |
| src/components/mask-input/mask-input.ts | JSDoc tense/wording cleanup |
| src/components/input/input.ts | Adds missing component summary + property description wording cleanup |
| src/components/input/input-base.ts | JSDoc property description wording cleanup |
| src/components/icon/registry/types.ts | Adds missing exported-type docs + wording cleanup |
| src/components/icon/icon.ts | JSDoc wording cleanup |
| src/components/file-input/file-input.ts | JSDoc wording cleanup for native attributes |
| src/components/expansion-panel/expansion-panel.ts | Adds missing @returns docs for async API |
| src/components/dropdown/dropdown.ts | JSDoc grammar (“opened”) + wording cleanup |
| src/components/dropdown/dropdown-item.ts | JSDoc csspart wording cleanup |
| src/components/dropdown/dropdown-header.ts | JSDoc grammar fix |
| src/components/dropdown/dropdown-group.ts | JSDoc wording cleanup |
| src/components/divider/divider.ts | JSDoc readability/line-break fix |
| src/components/date-time-input/date-time-input.base.ts | JSDoc placeholder wording cleanup |
| src/components/date-time-input/date-part.ts | Adds missing public type docs (DatePartDeltas) |
| src/components/date-range-picker/predefined-ranges-area.ts | JSDoc wording cleanup |
| src/components/date-range-picker/date-range-picker.ts | JSDoc description + event wording (popover vs dropdown) |
| src/components/date-picker/date-picker.ts | JSDoc description + event wording (popover vs dropdown) |
| src/components/common/mixins/forms/types.ts | Form-associated API doc wording/grammar fixes |
| src/components/common/mixins/forms/associated.ts | Form-associated API doc wording/grammar fixes |
| src/components/combo/types.ts | JSDoc punctuation/wording cleanup |
| src/components/combo/combo.ts | JSDoc wording cleanup |
| src/components/chip/chip.ts | Fixes misleading event description (igcRemove) |
| src/components/checkbox/checkbox-base.ts | JSDoc wording cleanup |
| src/components/chat/types.ts | JSDoc punctuation/wording cleanup |
| src/components/chat/chat.ts | JSDoc wording cleanup |
| src/components/chat/chat-message.ts | JSDoc wording cleanup |
| src/components/chat/chat-input.ts | JSDoc event/csspart wording cleanup |
| src/components/carousel/carousel.ts | JSDoc description + wording cleanup |
| src/components/carousel/carousel-slide.ts | JSDoc description wording cleanup |
| src/components/carousel/carousel-indicator.ts | JSDoc description wording cleanup |
| src/components/card/card.ts | Slot description wording cleanup |
| src/components/card/card.media.ts | JSDoc wording cleanup |
| src/components/card/card.content.ts | JSDoc wording cleanup |
| src/components/calendar/types.ts | Adds missing public type docs (DateRangeDescriptor) |
| src/components/calendar/calendar.ts | Corrects hideOutsideDays description polarity |
| src/components/calendar/base.ts | Fixes typo/grammar in values description |
| src/components/button/button.ts | JSDoc csspart wording cleanup |
| src/components/button-group/toggle-button.ts | JSDoc wording cleanup + value description |
| src/components/button-group/button-group.ts | Slot description wording cleanup |
| src/components/badge/badge.ts | JSDoc csspart wording cleanup |
| src/components/accordion/accordion.ts | JSDoc wording cleanup |
| .github/skills/review-component-pr/SKILL.md | Updates review checklist with doc conventions + generated-region guidance |
| .github/skills/create-new-component/SKILL.md | Adds “Documentation Conventions” and regeneration guidance |
| .github/skills/add-component-property/SKILL.md | Adds doc-writing rules + generated metadata regeneration steps |
Suppressed comments (1)
stories/date-picker.stories.ts:170
- The locale description uses "Gets/Sets…", which this PR is otherwise trying to eliminate (and it will be copied verbatim into wrapper docs). To keep generated stories in sync, please update the source JSDoc for
localeinsrc/components/date-picker/date-picker.tsand then rerunnpm run cem && npm run build:metaso the generated region picks up the declarative wording (e.g. "The locale used for formatting the display value.").
Comment on lines
75
to
+76
| /** | ||
| * The `igc-carousel` presents a set of `igc-carousel-slide`s by sequentially displaying a subset of one or more slides. | ||
| * The carousel presents a set of slides by sequentially displaying a subset of one or more. |
Comment on lines
29
to
32
| description: { | ||
| component: | ||
| 'The `igc-carousel` presents a set of `igc-carousel-slide`s by sequentially displaying a subset of one or more slides.', | ||
| 'The carousel presents a set of slides by sequentially displaying a subset of one or more.', | ||
| }, |
Comment on lines
+6
to
10
| * Used for defining gradient stops in the circular progress component. | ||
| * For each circular gradient, defined as `gradient` slot of the circular progress, would be created a SVG stop element. | ||
| * The values passed as `color`, `offset` and `opacity` would be set as | ||
| * `stop-color`, `offset` and `stop-opacity` of the SVG element without further validations. | ||
| * |
| let nextId = 1; | ||
|
|
||
| /** | ||
| * The radio component allows the user to select a single option from an available set of options that are listed side by side. |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 94 out of 94 changed files in this pull request and generated no new comments.
Suppressed comments (4)
src/components/carousel/carousel.ts:77
- The updated carousel summary is grammatically incomplete (“one or more” what?). Since this text is used verbatim in generated API docs and
custom-elements.json, it should be a complete sentence.
/**
* The carousel presents a set of slides by sequentially displaying a subset of one or more.
*
stories/carousel.stories.ts:32
- The story’s component description mirrors the same incomplete sentence (“one or more” what?), which will surface in Storybook docs. Update it to match the corrected JSDoc summary.
stories/date-picker.stories.ts:169 - The PR updates skills/docs to avoid “Gets/Sets …” phrasing in public descriptions, but this newly added locale description still uses it. Consider switching to declarative wording so it reads well in generated docs across wrappers.
src/components/expansion-panel/expansion-panel.ts:184 - The
show()method returnsfalsewhen the panel is already open (if (this.open) return false;), but the new@returnstext says "already closed", which is the opposite state and will mislead consumers of the generated docs.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 94 out of 94 changed files in this pull request and generated no new comments.
Suppressed comments (3)
src/components/progress/circular-gradient.ts:9
- Grammar: "would be created a SVG stop element" is ungrammatical; also "a SVG" should be "an SVG".
stories/date-picker.stories.ts:170 - This story is inside a generated
// region defaultblock, but the newlocaledescription uses "Gets/Sets", which contradicts the PR description's stated documentation conventions (declarative phrasing; no "Gets/Sets"). Since this text is generated from source JSDoc, it should be fixed in the component JSDoc and then regenerated, otherwise it will keep reappearing.
src/components/expansion-panel/expansion-panel.ts:184 show()returnsfalsewhen the panel is already open (if (this.open) return false;), but the JSDoc says "false if already closed", which is misleading for consumers.
rkaraivanov
approved these changes
Aug 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A lot of found during IgniteUI/igniteui-blazor#286 and just fixing in the source. Split into multiple commits for ease of review purposes.
Documentation-only pass over JSDoc descriptions. No runtime changes.
Why
Every description on a component, property, method, event, slot or CSS part is copied verbatim into
custom-elements.json, the generated Storybook story metadata, and the published API docs for Angular / React / Blazor. A typo or a wrong description doesn't stay in the source — it ships to every consumer, in four framework flavours.What changed
igc-tag names removed from prose (~30 components). Descriptions referred to components by tag name (`igc-carousel`,<igc-chat>,igc-textarea), which is meaningless in the framework wrapper docs. Covers component descriptions,@csspart,@slot,@firesand public members. Tag names kept where correct:@element,@exampleblocks, literal event names like"igc-change-theme", and internal-only members.Manifest scan: 76 → 21 descriptions containing
igc-, all 21 remaining internal-only.Descriptions that were factually wrong — see the list below.
Redundant phrasing.
The label attribute of the control.→The label of the control.(@attralready says it's an attribute);Gets/Sets …replaced with declarative wording; booleans now readWhether …and describe thetruestate. Applied to all ~30 occurrences, includingnameon the shared form-associated mixin (so it lands on every form control) and the native attributes onigc-input/igc-file-input.Typos and grammar (~15):
use→userinteractions,tha→the,ot→of,comma separate string→separated,DropDown→Dropdown,if it invalid→if it's invalid, and a few future → present tense fixes.Missing docs added.
igc-inputandigc-radiohad no component description at all (empty summary in Storybook). AlsoDateRangeDescriptor.dateRange,DatePartDeltas,IconMeta, and@returnson the expansion panel'stoggle()/hide()/show().Regenerated Storybook metadata via
npm run cem && npm run build:meta. All generated (// region default); several stories had drifted out of sync with the source.stories/splitter.stories.tshas no region markers and was updated by hand.stories/datepicker.stories.ts→date-picker.stories.ts(rename).build-stories.mjsderives the story filename from the tag name, so forigc-date-pickerit looked fordate-picker.stories.ts, didn't find it, and logged "No story file found for IgcDatePickerComponent, skipping." — silently, on every build. The file had not been regenerated since the tag was renamed fromigc-datepicker, and had drifted badly:component: 'igc-datepicker'pointed at a tag that no longer exists (so Storybook's docs and controls binding resolved to nothing, while the story's own templates correctly used<igc-date-picker>), the component description still literally began "igc-datepicker is a feature rich component…", andrequired/disabled/invalid/displayFormat/localedescriptions plus thesummarydefault quoting were all stale.Renaming reconnects it to the generator. Regeneration is idempotent, and drops the
locale: 'en'arg default, matching combo / date-range-picker / date-time-input / calendar, none of which seedlocaleeither.Note for reviewers: this changes
title: 'Datepicker'→'DatePicker', so the story's Storybook URL changes. Nothing else in the repo referenced the old filename or title.igc-date-pickerwas the only component affected by this filename-mismatch trap.Corrected descriptions worth a look
These were misleading rather than just clumsy:
calendar.hideOutsideDays— said "Whether to show the dates…". It hides them.carousel.hideIndicators— said "should render the indicator controls". It skipsrendering them.
chipigcRemove— claimed "Returns the removed chip component." The event isCustomEvent<boolean>emitted with no detail.nav-drawer-itemdisabled/active— described the drawer, not the item.it's a popover.
calendar.values— "selection is set to multiple of range" → "or range".Preventing regressions
The rules weren't written down anywhere, so each new component reintroduced them. Updated three
skills under
.github/skills/:Verification
check-types,lint:biomeandlint:prettierall clean.cem+build:metaidempotent — a second run produces no diff.