Untargeted property links are incorrectly formatted

Topics: User Forum
Dec 26, 2009 at 12:17 AM
Edited Jan 22, 2010 at 9:06 PM


With a <see cref="class.property"/> doc-comment where the class.property is resolved to a valid reference but there is no documentation to link to, the rendered text is property() rather than the correct property. That is, the trailing parentheses should be omitted. If it resolves to a valid reference and there is also documentation to link to, then it correctly omits the parentheses and it correctly gets a hyperlink.

 

Jan 22, 2010 at 9:07 PM

Some additional information that may spur some thoughts on this overlooked topic...

As a concrete example I have this in one C# doc-comment:

/// The <see cref="SyntaxHighlightingTextBox.EnableHighlighting"/> property ...

The class containing that doc-comment inherits from SyntaxHighlightingTextBox so it is a valid reference. However, the code for SyntaxHighlightingTextBox comes from a separate DLL which is not included in the documentation generation. In the final generated HTML that line renders as:

The EnableHighlighting() property

with the property name emboldened and an erroneous set of parentheses attached--a bug in the XSLT perhaps...? For completeness, I should state that when the property reference resolves to a valid link elsewhere in the documentation tree, then the formatting is correct, without the extraneous parentheses.

Coordinator
Jan 23, 2010 at 2:10 AM
Edited Jan 23, 2010 at 2:11 AM

It's probably a quirk in the way the Sandcastle transformations handle unresolved link elements.  As I recall, there's script in the pages that tries to render them with a language specific format or a language neutral format if multiple languages are selected for display (i.e. arrays are shown as X[] for C# and X() for VB.NET or multiple languages).  For the unresolved link it may not be able to tell it's a property or isn't rendered with enough info and defaults to showing method parentheses as a fall back of some sort.  You could use the Additional Reference Links plug-in to provide link information for the undocumented library so that it provides appropriate formatting.  Basically, you create a separate project for the undocumented assembly, add it to the plug-in and tell it to render links with the None format for items in that project.

Eric