Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Xml Doc comment cleanup reassessed #234

Merged
merged 4 commits into from
Mar 15, 2024
Merged

Conversation

abelbraaksma
Copy link
Member

@abelbraaksma abelbraaksma commented Mar 15, 2024

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 abelbraaksma force-pushed the doc-cleanup-reassessed branch 3 times, most recently from e56d034 to e412f7b Compare March 15, 2024 02:06
@abelbraaksma abelbraaksma force-pushed the doc-cleanup-reassessed branch from e412f7b to 79d55ec Compare March 15, 2024 02:07
@abelbraaksma
Copy link
Member Author

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

@abelbraaksma abelbraaksma requested a review from bartelink March 15, 2024 02:07
@abelbraaksma abelbraaksma added documentation Improvements or additions to documentation cleanup labels Mar 15, 2024
@abelbraaksma abelbraaksma self-assigned this Mar 15, 2024
@abelbraaksma abelbraaksma merged commit 9338100 into main Mar 15, 2024
4 checks passed
@abelbraaksma abelbraaksma deleted the doc-cleanup-reassessed branch March 15, 2024 02:36
@abelbraaksma abelbraaksma added this to the v0.4.0 milestone Mar 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cleanup documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants