Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions CodeBlocker.Test/DocCommentTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -369,6 +369,117 @@ public void ALineBreakInAnAttributeValueIsRejectedBeforeWriting(string terminato
}
}

[TestMethod]
public void BlankCrefsAreNotWritten()
{
// ktsu-dev/CodeBlocker#208: each of these was written as cref="" or cref=" " (CS1584).
DocComment documentation = new() { InheritDoc = true, InheritDocCref = " " };
documentation.SeeAlso.Add("");
documentation.SeeAlso.Add(" ");
documentation.SeeAlso.Add(null!);
documentation.SeeAlso.Add("Other");
documentation.Exceptions.Add(new DocTag { Name = "", Text = "x" });
documentation.Exceptions.Add(new DocTag { Name = " \t", Text = "x" });
documentation.Exceptions.Add(new DocTag { Name = null!, Text = "x" });
documentation.Exceptions.Add(new DocTag { Name = "InvalidOperationException", Text = "y" });

Assert.AreEqual(
"""
/// <inheritdoc/>
/// <exception cref="InvalidOperationException">y</exception>
/// <seealso cref="Other"/>

""".ReplaceLineEndings("\n"),
Render(documentation));
}

[TestMethod]
public void ACommentOfOnlyBlankCrefsIsEmpty()
{
DocComment documentation = new() { SeeAlso = { "", " " }, Exceptions = { new DocTag { Name = " ", Text = "x" } } };

Assert.IsTrue(documentation.IsEmpty);
Assert.AreEqual(string.Empty, Render(documentation));
}

[TestMethod]
public void ANullSeeAlsoEntryKeepsTheClassWhole()
{
// ktsu-dev/CodeBlocker#208: a null entry threw NullReferenceException and left the class
// without its member.
ClassTemplate type = new()
{
Name = "C",
Members =
{
new MethodTemplate
{
Type = "void",
Name = "M",
BodyFactory = _ => { },
Documentation = new DocComment { Summary = "hi", SeeAlso = { null! } },
},
},
};

using CodeBlocker codeBlocker = CodeBlocker.Create(CodeBlocker.DefaultIndentString, NewLines.Lf);
codeBlocker.AddClass(type);

Assert.AreEqual(
"""
class C
{
/// <summary>hi</summary>
void M() { }
}

""".ReplaceLineEndings("\n"),
codeBlocker.ToString());
}

[TestMethod]
public void ANullTagOrTagNameIsRejectedBeforeWriting()
{
DocComment[] comments =
[
new() { Summary = "s", Params = { null! } },
new() { Summary = "s", TypeParams = { null! } },
new() { Summary = "s", Exceptions = { null! } },
new() { Summary = "s", Params = { new DocTag { Name = null!, Text = "t" } } },
new() { Summary = "s", TypeParams = { new DocTag { Name = null!, Text = "t" } } },
];

foreach (DocComment documentation in comments)
{
using CodeBlocker codeBlocker = CodeBlocker.Create(CodeBlocker.DefaultIndentString, NewLines.Lf);
Assert.ThrowsExactly<ArgumentException>(() => documentation.WriteTo(codeBlocker));
Assert.AreEqual(string.Empty, codeBlocker.ToString(), "Nothing should be written before the check.");
}
}

[TestMethod]
public void ANullTagIsRejectedBeforeTheClassIsWritten()
{
ClassTemplate type = new()
{
Name = "C",
Members =
{
new MethodTemplate
{
Type = "void",
Name = "M",
BodyFactory = _ => { },
Documentation = new DocComment { Summary = "hi", Params = { null! } },
},
},
};

using CodeBlocker codeBlocker = CodeBlocker.Create(CodeBlocker.DefaultIndentString, NewLines.Lf);
Assert.ThrowsExactly<ArgumentException>(() => codeBlocker.AddClass(type));
Assert.AreEqual(string.Empty, codeBlocker.ToString());
}

[TestMethod]
public void AnUnusedInheritDocCrefIsNotChecked() =>
Assert.AreEqual(
Expand Down
60 changes: 46 additions & 14 deletions CodeBlocker/Templates/DocComment.cs
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ public class DocComment

/// <summary>
/// Gets or sets the <c>cref</c> of the member to inherit documentation from. Ignored unless
/// <see cref="InheritDoc"/> is set; empty writes a bare <c>&lt;inheritdoc/&gt;</c>.
/// <see cref="InheritDoc"/> is set; empty or white space writes a bare <c>&lt;inheritdoc/&gt;</c>.
/// </summary>
public string InheritDocCref { get; set; } = string.Empty;

Expand All @@ -70,10 +70,17 @@ public class DocComment
/// <summary>Gets the <c>&lt;param&gt;</c> entries, keyed by parameter name.</summary>
public Collection<DocTag> Params { get; } = [];

/// <summary>Gets the <c>&lt;exception&gt;</c> entries, keyed by exception type <c>cref</c>.</summary>
/// <summary>
/// Gets the <c>&lt;exception&gt;</c> entries, keyed by exception type <c>cref</c>. An entry whose
/// <see cref="DocTag.Name"/> is <see langword="null"/>, empty or white space is skipped: it would
/// be written as <c>cref=""</c>, which the compiler reports as CS1584.
/// </summary>
public Collection<DocTag> Exceptions { get; } = [];

/// <summary>Gets the <c>&lt;seealso&gt;</c> <c>cref</c> values.</summary>
/// <summary>
/// Gets the <c>&lt;seealso&gt;</c> <c>cref</c> values. A <see langword="null"/>, empty or white
/// space entry is skipped.
/// </summary>
public Collection<string> SeeAlso { get; } = [];

/// <summary>
Expand All @@ -87,8 +94,15 @@ public class DocComment
&& string.IsNullOrEmpty(Value)
&& TypeParams.Count == 0
&& Params.Count == 0
&& Exceptions.Count == 0
&& SeeAlso.Count == 0;
&& !WrittenExceptions.Any()
&& !WrittenSeeAlso.Any();

/// <summary>Gets the <see cref="Exceptions"/> entries that are written: those with a cref.</summary>
private IEnumerable<DocTag> WrittenExceptions =>
Exceptions.Where(exception => exception is not null && !string.IsNullOrWhiteSpace(exception.Name));

/// <summary>Gets the <see cref="SeeAlso"/> entries that are written: those that are not blank.</summary>
private IEnumerable<string> WrittenSeeAlso => TemplateRendering.NonBlank(SeeAlso);

/// <summary>
/// Writes the documentation in the canonical tag order: <c>inheritdoc</c>, <c>summary</c>,
Expand All @@ -100,7 +114,9 @@ public class DocComment
/// <exception cref="ArgumentException">
/// <see cref="InheritDocCref"/>, a <see cref="SeeAlso"/> entry, or the <see cref="DocTag.Name"/> of
/// a <see cref="TypeParams"/>, <see cref="Params"/> or <see cref="Exceptions"/> entry contains a
/// line break. Nothing is written.
/// line break; or <see cref="TypeParams"/>, <see cref="Params"/> or <see cref="Exceptions"/> holds
/// a <see langword="null"/> entry, or a <see cref="TypeParams"/> or <see cref="Params"/> entry has a
/// <see langword="null"/> <see cref="DocTag.Name"/>. Nothing is written.
/// </exception>
public void WriteTo(CodeBlocker codeBlocker)
{
Expand All @@ -112,7 +128,7 @@ public void WriteTo(CodeBlocker codeBlocker)

if (InheritDoc)
{
codeBlocker.WriteLine(string.IsNullOrEmpty(InheritDocCref)
codeBlocker.WriteLine(string.IsNullOrWhiteSpace(InheritDocCref)
? "/// <inheritdoc/>"
: $"/// <inheritdoc cref=\"{EscapeAttribute(InheritDocCref)}\"/>");
}
Expand All @@ -132,14 +148,14 @@ public void WriteTo(CodeBlocker codeBlocker)
WriteElement(codeBlocker, "returns", null, Returns);
WriteElement(codeBlocker, "value", null, Value);

foreach (DocTag exception in Exceptions)
foreach (DocTag exception in WrittenExceptions)
{
WriteNamedElement(codeBlocker, "exception", $" cref=\"{EscapeAttribute(exception.Name)}\"", exception.Text);
}

WriteElement(codeBlocker, "remarks", null, Remarks);

foreach (string cref in SeeAlso)
foreach (string cref in WrittenSeeAlso)
{
codeBlocker.WriteLine($"/// <seealso cref=\"{EscapeAttribute(cref)}\"/>");
}
Expand Down Expand Up @@ -197,7 +213,9 @@ void Check(Collection<DocTag> tags, HashSet<string> declared, string tagName, st
/// so a container refuses a bad doc comment before writing any of itself, not partway through.
/// </remarks>
/// <exception cref="ArgumentException">
/// <see cref="InheritDocCref"/>, a <see cref="SeeAlso"/> entry, or a tag name contains a line break.
/// <see cref="InheritDocCref"/>, a <see cref="SeeAlso"/> entry, or a tag name contains a line break;
/// a tag collection holds a <see langword="null"/> entry; or a <c>param</c> or <c>typeparam</c>
/// entry has a <see langword="null"/> name.
/// </exception>
internal void ValidateAttributes()
{
Expand All @@ -206,19 +224,33 @@ internal void ValidateAttributes()
EnsureSingleLine(InheritDocCref, "inheritdoc cref", nameof(InheritDocCref));
}

EnsureNamesSingleLine(TypeParams, "typeparam name", nameof(TypeParams));
EnsureNamesSingleLine(Params, "param name", nameof(Params));
EnsureNamesSingleLine(Exceptions, "exception cref", nameof(Exceptions));
// Null entries are refused here rather than found while writing, where they would throw a
// bare NullReferenceException with the doc comment, and its container, partly written. A
// blank exception cref is skipped when writing instead, like a blank seealso entry; a param
// or typeparam must name something, so a null name is refused.
EnsureNames(TypeParams, "typeparam name", nameof(TypeParams), nameRequired: true);
EnsureNames(Params, "param name", nameof(Params), nameRequired: true);
EnsureNames(Exceptions, "exception cref", nameof(Exceptions), nameRequired: false);

foreach (string cref in SeeAlso)
{
EnsureSingleLine(cref, "seealso cref", nameof(SeeAlso));
}

static void EnsureNamesSingleLine(Collection<DocTag> tags, string what, string paramName)
static void EnsureNames(Collection<DocTag> tags, string what, string paramName, bool nameRequired)
{
foreach (DocTag tag in tags)
{
if (tag is null)
{
throw new ArgumentException($"A doc comment has a null entry in {paramName}.", paramName);
}

if (nameRequired && tag.Name is null)
{
throw new ArgumentException($"A doc comment {what} must not be null.", paramName);
}

EnsureSingleLine(tag.Name, what, paramName);
}
}
Expand Down
Loading