镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

A blank SeeAlso or Exceptions cref, or a whitespace InheritDocCref, writes cref="" (CS1584), and a null SeeAlso entry throws NullReferenceException and leaves the class without that member #208

Open

Description

@matt-edmondson

What's wrong

DocComment treats an empty InheritDocCref as "no cref" and writes a bare <inheritdoc/> (CodeBlocker/Templates/DocComment.cs:115). That is the only place blank crefs are handled:

  • Blank crefs are written as-is. A whitespace InheritDocCref, a blank or whitespace SeeAlso entry, and a blank Exceptions[i].Name are each written as cref="" or cref=" " by the loops at DocComment.cs:135-151. ValidateAttributes (:200-222) checks these values only for line breaks.
  • A null entry throws mid-write. A null SeeAlso entry passes ValidateAttributes, then throws a NullReferenceException in EscapeAttribute while the doc comment is being written. By then the class has already been partly written. The same applies to a DocTag whose Name is null.

Elsewhere the library skips blank list entries (TemplateRendering.NonBlank, #197) and refuses null ones before writing anything (#198/#199). These two lists do neither.

Repro (HEAD 032f69a)

var d = new DocComment { InheritDoc = true, InheritDocCref = "  " };
d.SeeAlso.Add(""); d.SeeAlso.Add("  ");
d.Exceptions.Add(new DocTag { Name = "", Text = "x" });
c.Members.Add(new MethodTemplate { Name = "M", Type = "void", Documentation = d, BodyFactory = ... });
cb.AddClass(c);
class C
{
	/// <inheritdoc cref="  "/>
	/// <exception cref="">x</exception>
	/// <seealso cref=""/>
	/// <seealso cref="  "/>
	void M()
	{
	}
}

When this output is compiled with GenerateDocumentationFile, each of those lines reports warning CS1584: XML comment has syntactically incorrect cref attribute '' plus CS1658. Under TreatWarningsAsErrors they become build errors.

With d.SeeAlso.Add(null!) (Summary = "hi"), AddClass throws NullReferenceException and leaves:

class C
{
	/// <summary>hi</summary>
}

Why it matters

Generators build these lists from data, such as the exceptions a source method documents or "see also" links taken from metadata. A missing or blank value there turns the generated project's build red. A null value leaves a corrupt partial output and a bare NullReferenceException, which is the #164/#198 symptom again.

Suggested fix / acceptance criteria

  • Skip null or whitespace SeeAlso entries and Exceptions entries whose Name is blank, as NonBlank does for other lists.
  • Treat a whitespace InheritDocCref like an empty one, and write a bare <inheritdoc/>.
  • If null entries should be rejected rather than skipped, have ValidateAttributes refuse a null DocTag and a null SeeAlso entry or Name before anything is written, matching Refuse a null parameter, member or nested type before writing [patch] #199.
  • Add tests: blank and whitespace crefs produce no cref="" lines, and a null entry either is skipped or throws before any output is written.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

bugSomething isn't working

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions