Commit 28adb4f
authored
Overhaul XML documentation for ObservableListEx extension methods (#1081)
* docs: overhaul XML comments for ObservableListEx extension methods
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
* docs: add event tables to remaining list operators
Add event behavior tables to OnItemAdded, OnItemRemoved, ForEachChange,
WhereReasonsAre, TransformAsync, QueryWhenChanged, and other operators
that were missing them. Fix last old-style param description.
* docs: fix review findings in list operator docs
- 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)
* docs: remove internal type names from public XML comments
Replace references to ChangeSetMergeTracker and ChangeAwareList with
behavioral descriptions. Public docs should describe functionality,
not implementation details.
* docs: replace inline YieldWithoutIndex references with seealso links
Describe the behavior (index information is stripped) without naming the
method inline. Link YieldWithoutIndex via seealso on RemoveIndex,
WhereReasonsAre, and WhereReasonsAreNot.
* docs: link types with see/cref instead of inline code tags
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.
* docs: add type links to all param descriptions in list operators
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.
* docs: fix CS1712 warning for AutoRefresh typeparam
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.
* docs: use see langword for C# keywords (true, false, null)
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.
* docs: add cross-links from list operators to cache equivalents
27 primary list operators now link to their cache counterpart via seealso,
enabling navigation between the two collection types in generated docs.
* Fix param descriptions: proper English with type links
- 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
* Perfect param descriptions: purpose verbs, combined crefs, no redundancy
- 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
* Fix review findings: dangling prepositions, missing purposes
- 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
* Eliminate trailing prepositions in param descriptions
Rewrite dangling 'from.' prepositions in Except, ExpireAfter, LimitSizeTo,
RemoveIndex, and Top source params.1 parent b966943 commit 28adb4f
3 files changed
Lines changed: 1491 additions & 1011 deletions
0 commit comments