Cleanup code inspections / xmldoc rendering

[bartelink]

Calved from #220: small cleanups per Rider suggestions, and adding dictionary entries covering terms used in the repo.

Also:

• Rider complains about the new on the IAsyncDisposable being redundant. In this instance, I think the most direct thing to resolve it is to just not do that - the Dispose impl is not doing Async things. But, as we discussed, it's bad news that the tooling is suggesting dropping the new / not making the fact it's a disposable stick out.
  • https://github.com/JetBrains/resharper-fsharp/issues/589 requested Rider to not suggest removing
• Rider complains about paramrefs that are not correct (dont reference actual things), but we are using them here as its the only way to have VS+VSCode highlight types or snippets in bold (and Rider does not render <c> in bold either)

[abelbraaksma]

EDIT: the below may not matter much after I found out that using IDisposable may actually be the preferred coding pattern in this particular case, and nothing of this is in public facing code, so I'm fine with the change

---

Original post:

direct thing to resolve it is to just not do that

Ehm, you mean to not use new, or to not implement/use IAsyncDisposable?

the Dispose impl is not doing Async things

but the IAsyncDisposable impl is doing Async things. In other words, the general rule "use new with disposable stuff holds for both IDisposable and IAsyncDisposable. Which means, if you use use inside a CE, it will dispose using the async method. If your implementation also supports non-async disposing, it may also implement IDisposable and work with use outside a CE block.

it's bad news that the tooling is suggesting dropping the new / not making the fact it's a disposable stick out.

Indeed, so we shouldn't drop new ;).

Granted, I may not get your point here, really 😆.

Related, this discussion shows that IAsyncDisposable should be preferred inside CE: https://github.com/dotnet/fsharp/issues/12563

I'll write something up to figure this out conclusively.

[abelbraaksma]

I've taken the liberty to squash these commits a bit, and fixed some small errors in xml doc tags, plus removed some "legalese" wording 😆. I think it is good to be merged now.

The idisposable part is now in #227 (which makes the branch name a little odd here, lol).

[bartelink]

Yes all these cleanup ones I'd prefer them to be squash merged (I'm a fan of the linear history tickbox)

[abelbraaksma]

squash merged (I'm a fan of the linear history tickbox)

Yeah, that's not supported on this repo, I do like to see informed and well-written commits. Squash-merging defeats that purpose. But I do keep a linear history, and require rebasing.