Skip to content

docs: fill in public API XML docs, types and fixes - #286

Merged
damyanpetev merged 2 commits into
masterfrom
dpetev/xml-docs
Aug 4, 2026
Merged

docs: fill in public API XML docs, types and fixes#286
damyanpetev merged 2 commits into
masterfrom
dpetev/xml-docs

Conversation

@damyanpetev

@damyanpetev damyanpetev commented Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Fills in the missing XML docs across the component wrappers, sourced from the Ignite UI Web Components metadata rather than written from scratch, then reviewed and adapted so they read as .NET API documentation. Comments that were already present but unusable — imported markdown, JavaScript vocabulary, a few statements outright wrong for Blazor — are fixed in the same pass.

Comment lines only: no code, signatures, attributes or member order were touched.

Where the text comes from

Source Used for
custom-elements.json (CEM) Component class summaries, properties, events, methods
Shipped *.d.ts typings Interfaces the CEM omits (chat options and render contexts, filtering options, highlight navigation) and @internal members it strips (HasDateParts, HasTimeParts)
The wrappers themselves Event-args and payload types, which have no upstream description at all — derived from the events that carry them, the serialized payload keys, and the upstream emit sites
Hand-written Blazor-only surface: focus/blur, two-way binding callbacks, resource modules, *Script parameters

Filled in

  • Components — class summaries, [Parameter] properties, events and methods, including both overloads of every sync/async pair (upstream documents only the async one) and the read-only value accessors such as GetCurrentValue and GetTotal.
  • Event args and payload types — undocumented across the board and absent from the manifest, so each was derived from the events that raise it and the payload it actually carries.
  • *Script parameters — public API with no documentation until now. Event handlers point at the event they replace, template renderers describe what they render, and both show the igRegisterScript registration.
  • Base types — each now states which components it backs instead of standing unexplained.
  • AddIgniteUIBlazor and the client resource modules, including when registering explicitly is actually needed.

Fixed

  • Markdown that never rendered — backticks, links and bullet lists became <c>, <see langword="…"/>, <see href="…"> and <list type="bullet"> with resolved enum crefs.
  • Web component vocabulary — igc-card reads as <see cref="IgbCard"/>, `show()` as <see cref="Show"/>, "returns a promise that resolves to" as "returns", and DOM-only advice with no Blazor equivalent is gone.
  • Statements that were wrong here — Chip.Remove claimed to return the removed chip though the event carries a bool; DateTimeInput.Change described a "checked state"; the calendar range strings were described as labels when they are placeholders; "Cancelable." was dropped from -ing events, since Blazor's async round trip cannot cancel.
  • Structure — return values moved into <returns> with consistent phrasing, and cross references point at the component a consumer uses rather than an internal base type.

Verification

  • dotnet build clean: 0 errors, 0 doc-syntax warnings — no malformed XML (CS1570), no parameter mismatches (CS1572/1573), no unresolved or ambiguous crefs (CS1574/CS0419).
  • Missing-doc warnings (CS1591) drop substantially. What remains is wrapper plumbing (constructors, Type, FindByName, serialization overrides, render flags) and the enums, all deliberately left alone pending future updates.

Defects found while documenting — not fixed here

Documenting the API surface surfaced these; each needs a code change and its own decision:

  1. IgbDropdown.Toggle(Object) never toggles — invokes "show" instead of "toggle", so the sync overload can only open the dropdown. fix(dropdown): target overloads - toggle interop method, return types #288
  2. AddIgniteUIBlazor(settings) discards modules — with no modulesToLoad params, it calls WithModulesToLoad(null) and clears whatever the settings carried. AddIgniteUIBlazor fix loading modules in settings overload, docs and test coverage #312
  3. Wrapper defaults disagree with upstream in a couple of dozen places — Tooltip.ShowDelay is 0 where upstream is 200, Textarea.Rows 0 vs 3, SpinLoop false vs true, Tile.ColSpan/RowSpan 0 vs 1. Behavior is correct — a property that was never assigned is not serialized, so the component keeps its own default — but reading the property returns the wrong value. Align component property defaults with the web components, unit & integration checks #292
  4. IgbDateRangePickerResourceStrings has no properties — upstream declares its own plus the inherited calendar strings, so the picker cannot be localized through that parameter. fix: date range resources - extend calendar & extra props #295
  5. Dead surface — IgbCalendarDate / IgbCalendarDateEventArgs have no upstream counterpart and nothing references them; CalendarResourceStrings.SelectedDate is mapped to nothing upstream and has no effect. chore: remove orphaned CalendarDate and CalendarDateEventArgs #310

Copilot AI review requested due to automatic review settings August 3, 2026 06:51
@damyanpetev damyanpetev added the 📖 documentation Improvements or additions to documentation label Aug 3, 2026
Copilot AI reviewed Aug 3, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR improves the public API XML documentation across the Ignite UI for Blazor wrapper components and supporting types (modules, event args, payload models), aligning docs with .NET XML doc conventions and Blazor usage patterns.

Changes:

  • Filled in missing <summary>, <remarks>, <returns>, and parameter docs across many wrapper components, event args/payload types, and resource modules.
  • Replaced web-component / JavaScript-oriented wording with Blazor- and .NET-friendly phrasing and cross-references (<see cref=.../>, <see langword=.../>, lists, etc.).
  • Added documentation for two-way binding callbacks and *Script parameters that route events to client-side handlers.

Reviewed changes

Copilot reviewed 176 out of 176 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
src/componentsBase/WebInputs/Tab.cs Added XML docs for SelectedChanged (and uncovered a setter type-check bug).
src/componentsBase/WebInputs/Input.cs Added base-type and ValueChanging XML docs.
src/componentsBase/BaseRendererControl.cs Minor comment cleanup; added missing XML doc for notify parameter.
src/components/Blazor/VoidEventArgs.cs Added XML docs for void-payload event args.
src/components/Blazor/TreeSelectionEventArgsDetail.cs Added XML docs for tree selection payload and NewSelection.
src/components/Blazor/TreeSelectionEventArgs.cs Added XML docs for tree selection event args and Detail.
src/components/Blazor/TreeModule.cs Added XML docs for IgbTree resource module and Register.
src/components/Blazor/TreeItemComponentEventArgs.cs Added XML docs for tree item event args and Detail.
src/components/Blazor/TreeItemCollection.cs Added XML docs for observable tree item collection.
src/components/Blazor/TreeItem.cs Added XML docs for path/getters and expand/collapse/toggle sync methods.
src/components/Blazor/Tree.cs Added XML docs for *Script parameters and tree events.
src/components/Blazor/TooltipModule.cs Added XML docs for tooltip resource module and Register.
src/components/Blazor/Tooltip.cs Improved component/property/method docs; added sync method docs and event/script docs.
src/components/Blazor/ToggleButton.cs Converted web-component wording to .NET refs; added docs for focus/blur/click sync methods.
src/components/Blazor/ToastModule.cs Added XML docs for toast resource module and Register.
src/components/Blazor/Toast.cs Added XML docs for toast component summary.
src/components/Blazor/TileManagerModule.cs Added XML docs for tile manager resource module and Register.
src/components/Blazor/TileComponentEventArgs.cs Added XML docs for tile drag/resize event args and Detail.
src/components/Blazor/TileChangeStateEventArgsDetail.cs Added XML docs for tile state payload and properties.
src/components/Blazor/TileChangeStateEventArgs.cs Added XML docs for tile state event args and Detail.
src/components/Blazor/ThemeProviderModule.cs Added XML docs for theme provider resource module and Register.
src/components/Blazor/TextareaModule.cs Added XML docs for textarea resource module and Register.
src/components/Blazor/TabsModule.cs Added XML docs for tabs resource module and Register.
src/components/Blazor/Tabs.cs Added IgbTabs summary and method/event/script XML docs; refined enum refs and punctuation.
src/components/Blazor/Tabs_TabCollection.cs Added XML docs for observable tab collection.
src/components/Blazor/TabModule.cs Added XML docs for tab resource module and Register.
src/components/Blazor/TabComponentEventArgs.cs Added XML docs for tabs change event args and Detail.
src/components/Blazor/Tab.cs Updated tab summary to reference IgbTabs.
src/components/Blazor/SwitchModule.cs Added XML docs for switch resource module and Register.
src/components/Blazor/StepperModule.cs Added XML docs for stepper resource module and Register.
src/components/Blazor/Stepper.cs Added method docs and event/script docs for stepper.
src/components/Blazor/Step.cs Updated step summary to reference IgbStepper.
src/components/Blazor/SplitterResizeEventArgsDetail.cs Added payload docs; refined punctuation and event refs.
src/components/Blazor/SplitterResizeEventArgs.cs Added XML docs for splitter resize event args and Detail.
src/components/Blazor/SplitterModule.cs Added XML docs for splitter resource module and Register.
src/components/Blazor/Splitter.cs Refined component/property docs; added sync method docs and event/script docs.
src/components/Blazor/SnackbarModule.cs Added XML docs for snackbar resource module and Register.
src/components/Blazor/Snackbar.cs Added component summary and action event/script docs.
src/components/Blazor/SliderModule.cs Added XML docs for slider resource module and Register.
src/components/Blazor/SliderBase.cs Added base-type summary and updated property docs with cref/langword usage.
src/components/Blazor/Slider.cs Added method docs, two-way binding docs, and event/script docs; refined phrasing.
src/components/Blazor/SelectModule.cs Added XML docs for select resource module and Register.
src/components/Blazor/SelectItemComponentEventArgs.cs Added XML docs for select change event args and Detail.
src/components/Blazor/SelectHeader.cs Updated summary to reference IgbSelect.
src/components/Blazor/SelectGroup.cs Added component summary and updated items doc to use IgbSelectItem cref.
src/components/Blazor/RippleModule.cs Added XML docs for ripple resource module and Register.
src/components/Blazor/Ripple.cs Minor grammar fix in summary.
src/components/Blazor/RatingSymbol.cs Updated summary to reference IgbRating.
src/components/Blazor/RatingModule.cs Added XML docs for rating resource module and Register.
src/components/Blazor/RangeSliderValueEventArgs.cs Added XML docs for range slider value event args and Detail.
src/components/Blazor/RangeSliderValue.cs Added XML docs for range slider value payload and thumb properties.
src/components/Blazor/RangeSliderModule.cs Added XML docs for range slider resource module and Register.
src/components/Blazor/RangeSlider.cs Added event/script XML docs for input/change.
src/components/Blazor/RadioModule.cs Added XML docs for radio resource module and Register.
src/components/Blazor/RadioGroupModule.cs Added XML docs for radio group resource module and Register.
src/components/Blazor/RadioGroup.cs Improved summary and added method/value/event/script docs.
src/components/Blazor/RadioChangeEventArgsDetail.cs Added XML docs for radio change payload and properties.
src/components/Blazor/RadioChangeEventArgs.cs Added XML docs for radio/radiogroup change event args and Detail.
src/components/Blazor/ProgressBase.cs Added base-type summary and converted placeholder docs to <list>.
src/components/Blazor/NumberFormatSpecifier.cs Added type/property XML docs for number formatting specifier.
src/components/Blazor/NumberEventArgs.cs Added XML docs for numeric event args and Detail.
src/components/Blazor/NavDrawerModule.cs Added XML docs for nav drawer resource module and Register.
src/components/Blazor/NavDrawerItem.cs Corrected docs to say “drawer item” (not “drawer”).
src/components/Blazor/NavDrawerHeaderItem.cs Improved summary wording.
src/components/Blazor/NavbarModule.cs Added XML docs for navbar resource module and Register.
src/components/Blazor/MaskInputModule.cs Added XML docs for mask input resource module and Register.
src/components/Blazor/MaskInput.cs Added/converted docs to XML lists/crefs; added sync method docs and event/script docs.
src/components/Blazor/ListModule.cs Added XML docs for list resource module and Register.
src/components/Blazor/LinearProgressModule.cs Added XML docs for linear progress resource module and Register.
src/components/Blazor/InputModule.cs Added XML docs for input resource module and Register.
src/components/Blazor/InputBase.cs Refined property/method docs; added sync method docs; added event/script docs.
src/components/Blazor/Input.cs Added component summary; added sync method docs; refined property docs and event/script docs.
src/components/Blazor/IconModule.cs Added XML docs for icon resource module and Register.
src/components/Blazor/IconMeta.cs Added XML docs for icon metadata and Collection.
src/components/Blazor/IconButtonModule.cs Added XML docs for icon button resource module and Register.
src/components/Blazor/IconButton.cs Converted docs to lists/crefs; added icon registration method docs.
src/components/Blazor/Icon.cs Added icon registration / alias method docs.
src/components/Blazor/HighlightNavigation.cs Added type/property XML docs.
src/components/Blazor/HighlightModule.cs Added XML docs for highlight resource module and Register.
src/components/Blazor/Highlight.cs Added method docs and refined parameter docs; added sync variants’ docs.
src/components/Blazor/FormatSpecifier.cs Added base-type summary and docs for local culture getters.
src/components/Blazor/FocusOptions.cs Added type/property XML docs for focus options.
src/components/Blazor/FilteringOptions.cs Added type/property docs; refined wording and punctuation.
src/components/Blazor/ExpansionPanelModule.cs Added XML docs for expansion panel resource module and Register.
src/components/Blazor/ExpansionPanelComponentEventArgs.cs Added XML docs for expansion panel event args and Detail.
src/components/Blazor/ExpansionPanel.cs Refined property/method docs and added event/script docs with returns info.
src/components/Blazor/DropdownModule.cs Added XML docs for dropdown resource module and Register.
src/components/Blazor/DropdownItemComponentEventArgs.cs Added XML docs for dropdown change event args and Detail.
src/components/Blazor/DropdownItemCollection.cs Added XML docs for dropdown item collection.
src/components/Blazor/DropdownHeader.cs Improved summary wording.
src/components/Blazor/DropdownGroup.cs Improved summary wording.
src/components/Blazor/DividerModule.cs Added XML docs for divider resource module and Register.
src/components/Blazor/Divider.cs Improved divider summary wording and formatting.
src/components/Blazor/DialogModule.cs Added XML docs for dialog resource module and Register.
src/components/Blazor/DateTimeInputModule.cs Added XML docs for date-time input resource module and Register.
src/components/Blazor/DateTimeInputBase.cs Added base-type summary; refined property docs; added sync method docs.
src/components/Blazor/DateTimeInput.cs Added method docs and event/script docs; refined “clear” wording.
src/components/Blazor/DateRangeValueEventArgs.cs Added XML docs for date-range payload event args and Detail.
src/components/Blazor/DateRangeValueDetail.cs Added XML docs for date-range payload (start/end).
src/components/Blazor/DateRangeValue.cs Added XML docs for date range model (start/end).
src/components/Blazor/DateRangePickerModule.cs Added XML docs for date range picker resource module and Register.
src/components/Blazor/DateRangeDescriptor.cs Added type/property XML docs describing range semantics.
src/components/Blazor/DatePickerModule.cs Added XML docs for date picker resource module and Register.
src/components/Blazor/DatePartDeltas.cs Added type/property XML docs for spin deltas.
src/components/Blazor/CustomDateRange.cs Added type/property XML docs for date range picker custom ranges.
src/components/Blazor/ComponentValueChangedEventArgs.cs Added XML docs for string payload event args and Detail.
src/components/Blazor/ComponentDateValueChangedEventArgs.cs Added XML docs for date payload event args and Detail.
src/components/Blazor/ComponentDataValueChangedEventArgs.cs Added XML docs for object payload event args and Detail.
src/components/Blazor/ComponentBoolValueChangedEventArgs.cs Added XML docs for bool payload event args and Detail.
src/components/Blazor/ComboModule.cs Added XML docs for combo resource module and Register.
src/components/Blazor/ComboChangeEventArgs.cs Added XML docs for combo change event args and Detail.
src/components/Blazor/ComboBoxBaseLike.cs Added base-type summary listing derived components.
src/components/Blazor/CircularProgressModule.cs Added XML docs for circular progress resource module and Register.
src/components/Blazor/CircularGradientModule.cs Added XML docs for circular gradient resource module and Register.
src/components/Blazor/CircularGradient.cs Converted summary/property docs to .NET style with proper punctuation/refs.
src/components/Blazor/ChipModule.cs Added XML docs for chip resource module and Register.
src/components/Blazor/Chip.cs Added method docs, two-way binding docs, and event/script docs.
src/components/Blazor/CheckboxModule.cs Added XML docs for checkbox resource module and Register.
src/components/Blazor/CheckboxChangeEventArgsDetail.cs Added XML docs for checkbox/switch change payload and properties.
src/components/Blazor/CheckboxChangeEventArgs.cs Added XML docs for checkbox/switch change event args and Detail.
src/components/Blazor/ChatRenderContext.cs Added XML docs and updated instance wording.
src/components/Blazor/ChatOptions.cs Added type/property docs; converted option docs to lists/crefs and added guidance remarks.
src/components/Blazor/ChatModule.cs Added XML docs for chat resource module and Register.
src/components/Blazor/ChatMessageRenderContext.cs Added XML docs for message render context.
src/components/Blazor/ChatMessageReactionEventArgs.cs Added XML docs for message reaction event args and Detail.
src/components/Blazor/ChatMessageReaction.cs Added XML docs for reaction model.
src/components/Blazor/ChatMessageEventArgs.cs Added XML docs for message-created event args and Detail.
src/components/Blazor/ChatMessageAttachmentEventArgs.cs Added XML docs for attachment-click event args and Detail.
src/components/Blazor/ChatMessageAttachment.cs Added XML docs for attachment model.
src/components/Blazor/ChatMessage.cs Added XML docs for chat message model.
src/components/Blazor/ChatInputRenderContext.cs Added XML docs for input render context.
src/components/Blazor/ChatAttachmentRenderContext.cs Added XML docs for attachment render context.
src/components/Blazor/Chat.cs Added sync method docs plus event/script XML docs for chat events.
src/components/Blazor/CarouselSlide.cs Updated summary to reference IgbCarousel.
src/components/Blazor/CarouselModule.cs Added XML docs for carousel resource module and Register.
src/components/Blazor/CarouselIndicator.cs Updated summary to reference IgbCarousel.
src/components/Blazor/CardModule.cs Added XML docs for card resource module and Register.
src/components/Blazor/CardMedia.cs Updated summary to reference IgbCard.
src/components/Blazor/CardContent.cs Updated summary to reference IgbCard.
src/components/Blazor/CalendarModule.cs Added XML docs for calendar resource module and Register.
src/components/Blazor/CalendarFormatOptions.cs Added XML docs for calendar format options and usage.
src/components/Blazor/CalendarBase.cs Added base-type summary for IgbCalendar.
src/components/Blazor/Calendar.cs Added property/method docs and two-way binding docs; refined header/outside-days wording; added event/script docs.
src/components/Blazor/ButtonModule.cs Added XML docs for button resource module and Register.
src/components/Blazor/ButtonGroupModule.cs Added XML docs for button group resource module and Register.
src/components/Blazor/ButtonGroup.cs Updated summary; added docs for SelectedItems and event/script docs.
src/components/Blazor/Button.cs Added component summary and converted variant docs to <list> with enum crefs.
src/components/Blazor/BaseOptionLike.cs Added base-type summary and refined value docs.
src/components/Blazor/BaseComboBox.cs Added base-type summary and sync method <returns> docs for show/hide/toggle.
src/components/Blazor/BaseAlertLike.cs Added base-type summary; converted docs to lists/crefs; added sync method return docs.
src/components/Blazor/BannerModule.cs Added XML docs for banner resource module and Register.
src/components/Blazor/Banner.cs Added component summary; updated method docs and added event/script docs.
src/components/Blazor/BadgeModule.cs Added XML docs for badge resource module and Register.
src/components/Blazor/AvatarModule.cs Added XML docs for avatar resource module and Register.
src/components/Blazor/ActiveStepChangingEventArgsDetail.cs Added XML docs for active-step-changing payload and indexes.
src/components/Blazor/ActiveStepChangingEventArgs.cs Added XML docs for active-step-changing event args and Detail.
src/components/Blazor/ActiveStepChangedEventArgsDetail.cs Added XML docs for active-step-changed payload.
src/components/Blazor/ActiveStepChangedEventArgs.cs Added XML docs for active-step-changed event args and Detail.
src/components/Blazor/AccordionModule.cs Added XML docs for accordion resource module and Register.
src/components/Blazor/Accordion.cs Added sync method docs; added event/script docs for panel open/close events.

Comment thread src/componentsBase/WebInputs/Tab.cs
Comment on lines +9 to +12
/// <summary>
/// Emitted when the Selected property changes.
/// Enables two-way binding through <c>@bind-Selected</c>.
/// </summary>

@damyanpetev damyanpetev Aug 3, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, cool, one more issue unlocked. To address separately though.

@damyanpetev damyanpetev Aug 5, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Covered in #315

Comment thread src/components/Blazor/DropdownItemCollection.cs
Comment on lines +3 to +5
/// <summary>
/// An observable collection of <see cref="IgbDropdownItem"/> instances
/// </summary>
@damyanpetev damyanpetev mentioned this pull request Aug 3, 2026
Merged
20 tasks
@dkamburov dkamburov self-assigned this Aug 3, 2026
@damyanpetev damyanpetev mentioned this pull request Aug 3, 2026
Merged
@damyanpetev damyanpetev added the squash-merge Merge PR with "Squash and Merge" option label Aug 3, 2026
This was referenced Aug 3, 2026
Draft
Merged
Open
Merged
dkamburov
dkamburov reviewed Aug 4, 2026
View reviewed changes
Comment thread src/components/Blazor/Accordion.cs
/// </summary>
/// <remarks>
/// Register the function on the client like
/// <c>igRegisterScript("MyHandler", function (args) { }, false)</c>.

@dkamburov dkamburov Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this can add blazor code as well OpeningScript="MyHandler" as well, but I guess it go without it

@dkamburov dkamburov Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess it can stay that way as well

@damyanpetev damyanpetev Aug 4, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I assume that's obvious. The register call isn't so I went with the noisy description.

@damyanpetev
damyanpetev merged commit dd66fc0 into master Aug 4, 2026
7 of 8 checks passed
@damyanpetev
damyanpetev deleted the dpetev/xml-docs branch August 4, 2026 14:51
This was referenced Aug 4, 2026
Merged
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@dkamburov dkamburov dkamburov approved these changes

Assignees

@dkamburov dkamburov

Labels

📖 documentation Improvements or additions to documentation squash-merge Merge PR with "Squash and Merge" option

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@damyanpetev @dkamburov