Skip to content

Commit 28adb4f

Browse files
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

File tree

0 commit comments

Comments
 (0)