diff --git a/CodeBlocker.Test/DocCommentTests.cs b/CodeBlocker.Test/DocCommentTests.cs
index 27dab1f..e6da72b 100644
--- a/CodeBlocker.Test/DocCommentTests.cs
+++ b/CodeBlocker.Test/DocCommentTests.cs
@@ -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(
+ """
+ ///
+ /// y
+ ///
+
+ """.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
+ {
+ /// hi
+ 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(() => 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(() => codeBlocker.AddClass(type));
+ Assert.AreEqual(string.Empty, codeBlocker.ToString());
+ }
+
[TestMethod]
public void AnUnusedInheritDocCrefIsNotChecked() =>
Assert.AreEqual(
diff --git a/CodeBlocker/Templates/DocComment.cs b/CodeBlocker/Templates/DocComment.cs
index 3a19a4a..7f93a64 100644
--- a/CodeBlocker/Templates/DocComment.cs
+++ b/CodeBlocker/Templates/DocComment.cs
@@ -48,7 +48,7 @@ public class DocComment
///
/// Gets or sets the cref of the member to inherit documentation from. Ignored unless
- /// is set; empty writes a bare <inheritdoc/>.
+ /// is set; empty or white space writes a bare <inheritdoc/>.
///
public string InheritDocCref { get; set; } = string.Empty;
@@ -70,10 +70,17 @@ public class DocComment
/// Gets the <param> entries, keyed by parameter name.
public Collection Params { get; } = [];
- /// Gets the <exception> entries, keyed by exception type cref.
+ ///
+ /// Gets the <exception> entries, keyed by exception type cref. An entry whose
+ /// is , empty or white space is skipped: it would
+ /// be written as cref="", which the compiler reports as CS1584.
+ ///
public Collection Exceptions { get; } = [];
- /// Gets the <seealso> cref values.
+ ///
+ /// Gets the <seealso> cref values. A , empty or white
+ /// space entry is skipped.
+ ///
public Collection SeeAlso { get; } = [];
///
@@ -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();
+
+ /// Gets the entries that are written: those with a cref.
+ private IEnumerable WrittenExceptions =>
+ Exceptions.Where(exception => exception is not null && !string.IsNullOrWhiteSpace(exception.Name));
+
+ /// Gets the entries that are written: those that are not blank.
+ private IEnumerable WrittenSeeAlso => TemplateRendering.NonBlank(SeeAlso);
///
/// Writes the documentation in the canonical tag order: inheritdoc, summary,
@@ -100,7 +114,9 @@ public class DocComment
///
/// , a entry, or the of
/// a , or entry contains a
- /// line break. Nothing is written.
+ /// line break; or , or holds
+ /// a entry, or a or entry has a
+ /// . Nothing is written.
///
public void WriteTo(CodeBlocker codeBlocker)
{
@@ -112,7 +128,7 @@ public void WriteTo(CodeBlocker codeBlocker)
if (InheritDoc)
{
- codeBlocker.WriteLine(string.IsNullOrEmpty(InheritDocCref)
+ codeBlocker.WriteLine(string.IsNullOrWhiteSpace(InheritDocCref)
? "/// "
: $"/// ");
}
@@ -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($"/// ");
}
@@ -197,7 +213,9 @@ void Check(Collection tags, HashSet declared, string tagName, st
/// so a container refuses a bad doc comment before writing any of itself, not partway through.
///
///
- /// , a entry, or a tag name contains a line break.
+ /// , a entry, or a tag name contains a line break;
+ /// a tag collection holds a entry; or a param or typeparam
+ /// entry has a name.
///
internal void ValidateAttributes()
{
@@ -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 tags, string what, string paramName)
+ static void EnsureNames(Collection 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);
}
}