DocComment silently drops a <param>/<typeparam> with empty text while Validate reports no issues, so generated code hits CS1573

[matt-edmondson]

What's wrong

DocComment.WriteElement (CodeBlocker/Templates/DocComment.cs ~186-189) returns without writing anything when the element text is null or empty. That is fine for summary/returns/value/remarks, but it also applies to the named tags param, typeparam and exception. Meanwhile:

• Validate(parameterNames, typeParameterNames) (~161-180) only compares names. A DocTag { Name = "b", Text = "" } counts as documenting b, so validation passes.
• IsEmpty (~80-90) counts Params.Count/TypeParams.Count, so a comment holding only an empty-text param reports IsEmpty == false but writes nothing.

Repro (reproduced with MSTest)

var doc = new DocComment { Summary = "S" };
doc.Params.Add(new DocTag { Name = "a", Text = "A" });
doc.Params.Add(new DocTag { Name = "b", Text = "" });

doc.Validate(["a", "b"], []);   // 0 issues
doc.WriteTo(codeBlocker);

Output:

/// <summary>S</summary>
/// <param name="a">A</param>

b has no <param> tag. When compiled, the generated method void M(int a, int b) gets CS1573 ("Parameter 'b' has no matching param tag in the XML comment"). Under TreatWarningsAsErrors, which the ktsu SDK enables, that is a build break. The generator author was told by Validate that the comment was complete.

Suggested fix / acceptance criteria

• Always write tags that carry a name/cref attribute (param, typeparam, exception), even with empty text, e.g. /// <param name="b"></param>. Keep the empty-skip only for summary, returns, value and remarks.
• Make IsEmpty agree with what WriteTo actually emits.
• Alternatively, if empty tags should stay suppressed, Validate must report The parameter 'b' has no <param> entry. for an empty-text entry.
• Add a regression test for the case above.

[matt-edmondson]

Triage

• Category: Bug
• Priority: Medium. Validate gives a false "complete" result, and the generated code then breaks the build under TreatWarningsAsErrors (CS1573). An empty-text param is an uncommon input, though, and the failure is loud at compile time rather than silent at runtime.
• Area / suggested assignee: CodeBlocker/Templates/DocComment.cs: WriteElement, Validate and IsEmpty. Owner: @matt-edmondson
• Duplicates / in progress: none found. No open PR in CodeBlocker.
• Next step: prefer the first option in the issue, which always emits named tags (param/typeparam/exception) even with empty text. It keeps Validate name-based and makes WriteTo agree with it. Align IsEmpty with what is actually written, and add the regression test from the repro. The issue has no bug label yet, so consider adding one.

---

Generated by Claude Code