Search code examples
.netxmldocumentationsandcastle

Using links to method's arguments in XML documentation leads to broken links in help file generated by SandCastle

I have a problem with proper resolving of link in <see cref=""/> tag when <see> points to a method's argument.

Here is an example:

<summary>
My method.
</summary>
<param name="arg1">Arg1</param>
<param name="arg2">Arg2</param>
<exception cref="ArgumentNullException">Either <see cref="arg1"/>
or <see cref="arg2"/> is <c>null</c></exception>
public void MyMethod(object arg1, object arg2)
{
  // code here...
}

After generating an XML documentation file both tags are translated to:

<see cref="!:arg1"/>
<see cref="!:arg2"/>

When SandCastle is generating help file from above XML file such warnings occurs:

Warn: ResolveReferenceLinksComponent2: Unknown reference link target '!:arg1'
Warn: ResolveReferenceLinksComponent2: Invalid reference link target '!:arg1'
Warn: ResolveReferenceLinksComponent2: Unknown reference link target '!:arg2'
Warn: ResolveReferenceLinksComponent2: Invalid reference link target '!:arg2'

and after all the output help file contains broken links to both arg1 and arg2.

Does anyone know how to resolve this issue?

Solution

  • The <see> tag is not intended for referencing parameters. Use <paramref> instead.