cref Attribute in .NET Doc Comments

I was having trouble finding the correct syntax for the cref attribute of the see tag (and the exception, seealso and other tags) in .NET doc comments. I tried Namespace.TypeName.MethodName and Namespace.TypeName.MethodName(ArgType) to no avail getting the error “XML comment on ‘foo’ has cref attribute ‘Namespace.TypeName.MethodName’ that could not be found.” Eventually I found this in Google’s cache (not on site anymore) that made things clearer:

Use the cref attribute to link to a type or member or the langword attribute to specify a language keyword. The body of the tag is ignored. Cref attributes have the form: a one-letter prefix (N, T, C, M, P, F, E), a colon, and a value. Here are some example crefs:

  • “N:” for Namespaces, example N:System
  • “T:” for Types (classes, structs, interfaces, enumerations), example: T:System.Byte
  • “C:” for Constructors, example: C:Gtk.Button()
  • “M:” for Methods, example: M:System.String.Substring(System.Int32,System.Int32) (the argument list is optional)
  • “P:” for Properties, example: P:System.AppDomain.CurrentDomain
  • “F:” for Fields, example: F:Gtk.TreeIter.Zero
  • “E:” for Events, example: E:Gtk.Button.Clicked

Common langword usages: <see langword=”null”/>, <see langword=”true”/>.

So I just needed to put “M:” on the front of my cref et voila no more compiler warning.

The original page, should it come back online, was at http://www.nullenvoid.com/mono/wiki/index.php/ECMAStyleDocumentation.

Leave a Reply

Your email address will not be published.