Overhaul XML documentation for ObservableListEx extension methods#1081
Open
dwcullop wants to merge 14 commits intoreactivemarbles:mainfrom
Open
Overhaul XML documentation for ObservableListEx extension methods#1081dwcullop wants to merge 14 commits intoreactivemarbles:mainfrom
dwcullop wants to merge 14 commits intoreactivemarbles:mainfrom
Conversation
Add event behavior tables using list-specific change reasons (Add, AddRange, Replace, Remove, RemoveRange, Moved, Refresh, Clear, OnError, OnCompleted), seealso cross-references, inheritdoc for secondary overloads, and Worth noting sections across all ObservableListEx operators (~124 overloads, ~60 unique). Key improvements: - 29 event behavior tables with list-specific change reason handling - 157 seealso cross-references linking related operators - 49 inheritdoc tags for secondary overloads with delta remarks - 19 Worth noting sections for non-obvious behavior - Multi-source operators have separate parent/child tables - All old-style generic param descriptions replaced
Add event behavior tables to OnItemAdded, OnItemRemoved, ForEachChange, WhereReasonsAre, TransformAsync, QueryWhenChanged, and other operators that were missing them. Fix last old-style param description.
- Fix MergeChangeSets Replace docs (was incorrectly claimed to decompose into Remove+Add; actually uses ReplaceOrAdd which emits a single Replace) - Add Moved exception documentation to Transform (throws UnspecifiedIndexException when indices are missing) - Standardize multi-source event table headers to Event (source) and Event (per-item observable)
Replace references to ChangeSetMergeTracker and ChangeAwareList with behavioral descriptions. Public docs should describe functionality, not implementation details.
Describe the behavior (index information is stripped) without naming the method inline. Link YieldWithoutIndex via seealso on RemoveIndex, WhereReasonsAre, and WhereReasonsAreNot.
Replace <c>IObservable<T></c>, <c>IList<T></c>, <c>Optional<T></c>, <c>CalculateDiff</c>, <c>ClearAndReplace</c> etc. with proper <see cref='...'/> links for discoverability. Internal adaptor class names replaced with behavioral descriptions.
Every param tag now mentions and links its type via see/cref. For example
'source' params link to IObservable{T} and IChangeSet{T}, 'scheduler'
params link to IScheduler, 'predicate' params link to Func{T, TResult},
transform factories link to Func or Task as appropriate.
Add missing typeparam tag for TObject on the specific-property AutoRefresh overload. When inheritdoc is combined with explicit typeparam tags for other type parameters, all type parameters must be explicitly declared.
Replace <c>true</c>, <c>false</c>, <c>null</c> with <see langword='true'/>, <see langword='false'/>, <see langword='null'/> for proper keyword rendering in generated HTML documentation.
27 primary list operators now link to their cache counterpart via seealso, enabling navigation between the two collection types in generated docs.
- Rewrite 111+ param descriptions to read as natural English with type links woven in
- Fix double-brace cref syntax ({{T}} to {T})
- Fix wrong types in cref attributes to match actual parameter types
- Fix Optional/Additional/Factory articles (An optional, The additional, A factory)
- Fix filterPolicy, options, resetThreshold descriptions
- Add cross-link seealso references to cache file operators
- Add operator-specific purpose verbs to 81 source params
- Combine all split IObservable{T}/IChangeSet crefs into single nested format
- Remove 'changeset stream' redundancy after IChangeSet type references
- Fix remaining grammar and article issues
- Rewrite dangling 'from.' prepositions in MergeMany/SubscribeMany params - Add purpose to readOnlyObservableCollection and MergeChangeSets other params - Fix 'to suppress/strip/skip X from.' trailing prepositions
Rewrite dangling 'from.' prepositions in Except, ExpireAfter, LimitSizeTo, RemoveIndex, and Top source params.
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
1 participant
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.
What
Complete rewrite of XML doc comments for ObservableListEx, covering ~60 unique operators and ~124 total overloads. Every operator now has publication-quality documentation suitable for extraction to the ReactiveUI docs site.
Why
The existing XML comments were shallow and generic ("Filters source using the specified filter observable predicate", "The source", "An observable which emits the change set"). Developers had to read the implementation source to understand how list operators actually behave, especially around the list-specific change reasons (AddRange, RemoveRange, Moved, Clear) that have no cache equivalent.
What changed
Event behavior tables: 31 operators now have a structured
<list type="table">documenting how eachListChangeReasonevent is handled, including the list-specific reasons: Add, AddRange, Replace, Remove, RemoveRange, Moved, Refresh, Clear, OnError, and OnCompleted. Multi-source operators (FilterOnObservable, MergeManyChangeSets) have separate parent-side and per-item-observable tables.Cross-references: 157
<seealso>tags linking related operators: async variants (Transform/TransformAsync), similar operators (Filter/FilterOnObservable/FilterOnProperty), complementary operators (Filter+AutoRefresh, Sort+Bind), and commonly confused operators (MergeMany vs MergeManyChangeSets vs MergeChangeSets).Secondary overloads: 49
<inheritdoc>tags with delta<remarks>for overloads that delegate to a primary."Worth noting" sections: 20 operators have a labeled section calling out non-obvious behavior: OnItemRemoved firing for all tracked items on disposal, Transform silently appending when Add index is out of bounds, MergeChangeSets forwarding Replace via ReplaceOrAdd (not decomposing into Remove+Add), per-item observable operators requiring at least one emission before items become visible, ListFilterPolicy differences (CalculateDiff vs ClearAndReplace), and more.
Summaries trimmed: Every summary is 1-3 sentences describing what the operator does. All behavioral detail lives in
<remarks>.Accuracy verification
Three review agents cross-checked the documentation against the actual implementation code:
UnspecifiedIndexException)