search

AArnott / Validation

Method input validation and runtime checks that report errors or throw exceptions when failures are detected.
Microsoft Public License
131 stars 22 forks source link

XML doc comments #46

Closed scottdorman closed 3 years ago

scottdorman commented 3 years ago

There are a lot of places in the doc comments where it uses the syntax of <c>null</c> rather than <see langword="null"/>, or doesn't do anything and just uses plain text "null". Should these be updated to use the <see langword="null"/> syntax?

As an example, here is what the updated comment (for Requires.NotNull<T>(T, string?) would look like: https://github.com/AArnott/Validation/blob/2378284a62d732a89454564afca189b48e7ba5ba/src/Validation/Requires.cs#L19-L26

/// <summary>
/// Throws an exception if the the specified parameter's value is <see langword="null" />.
/// </summary>
/// <typeparam name="T">The type of the parameter.</typeparam>
/// <param name="value">The value of the argument.</param>
/// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
/// <returns>The value of the parameter.</returns>
/// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see langword="null" />.</exception>
AArnott commented 3 years ago

I would accept a PR that fixes this. But I'm curious why it matters.

scottdorman commented 3 years ago

It's a bit of nit, to be fair, but the <see langword="null"/> translates to null reference (Nothing in Visual Basic) as text. Really, this applies to true and false as well.

AArnott commented 3 years ago

Interesting. Thanks for the info.

bjm-csse commented 3 years ago

Hey Scott, I am interested in working on this! Would you assign this to me please? Thanks!

scottdorman commented 3 years ago

@bjm-csse That would be great! I don't have the ability to assign issues, but @AArnott can when he's able to.