fsprojects / FSharp.Control.TaskSeq

A computation expression and module for seamless working with IAsyncEnumerable<'T> as if it is just another sequence
MIT License
93 stars 8 forks source link

Xml Doc comment cleanup reassessed #234

Closed abelbraaksma closed 7 months ago

abelbraaksma commented 7 months ago

This is based off of #220, but rebased against main, and with squashed and reordered commits.

Some changes had to be reverted, like an IDisposable implementation that was changed into an IAsyncDisposable one, which changes behavior, and may not work anymore with "normal" use applications (this was a product of rebasing, this change was not present in #220. But we do have to be careful here. Anything that is disposable must ALWAYS implement IDisposable. If the action that does the disposing is asynchronous, it may ALSO implement IAsyncDisposable, but this is not a requirement.)

Also, occurrences like the use of <code>...</code> in xml doc comments summaries needed to be removed (unfortunately). They lead to garbled popup descriptions in VSCode, and in Visual Studio there's no discernible difference at all (TODO: raise as bugs to the respective communities).

For instance, a section like this:

    /// <summary>
    /// Returns <see cref="true" /> if the task sequence contains no elements, <see cref="false" /> otherwise.
    /// <code>this is code!</code>.
    /// </summary>

is rendered like this:

image

Hence the use of hacks like <paramref>:

    /// Returns <see cref="true" /> if the task sequence contains no elements, <see cref="false" /> otherwise.
    /// <paramref name="this is code!" />.

this is, of course, not ideal, but it renders as follows, which is an improvement, but we'll need a more permanent fix: image

For the same reason, true and false are surrounded by <see cref tags. Note that in Visual Studio, the coloring is slightly better at times, but still not ideal. Trying to find the lowest common denominator is, frankly speaking, a mess.

abelbraaksma commented 7 months ago

This is ready. Many thanks for the hard work on the prose used in the function descriptions!