From 2b750e96395bac04747da49e565487dd4413ad23 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 15:25:35 +0000 Subject: [PATCH] Skip blank doc crefs and refuse null doc tags before writing [patch] A whitespace InheritDocCref, a blank SeeAlso entry and a blank Exceptions name were written as cref="" (CS1584). They are now skipped, and a whitespace InheritDocCref writes a bare . A null SeeAlso entry or exception name is skipped the same way. A null DocTag, or a param/typeparam with a null name, is refused by ValidateAttributes before anything is written, rather than throwing NullReferenceException with the class half written. Fixes ktsu-dev/CodeBlocker#208 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017vfJW2P5xiJJTm9Z4wJwcH --- CodeBlocker.Test/DocCommentTests.cs | 111 ++++++++++++++++++++++++++++ CodeBlocker/Templates/DocComment.cs | 60 +++++++++++---- 2 files changed, 157 insertions(+), 14 deletions(-) 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); } }