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:
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:
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.
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 anIAsyncDisposable
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 implementIDisposable
. If the action that does the disposing is asynchronous, it may ALSO implementIAsyncDisposable
, 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:
is rendered like this:
Hence the use of hacks like
<paramref>
:this is, of course, not ideal, but it renders as follows, which is an improvement, but we'll need a more permanent fix:
For the same reason,
true
andfalse
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.