Generics issue and newline and tabs in <code> tag

Topics: User Forum
Jul 5, 2007 at 9:55 PM
Edited Jul 5, 2007 at 9:55 PM
Hi there,

First of all... thumbs up! You did a very great job. I do have two minor issues which I would like to notify you of.

First. When I have a parameter e that has e <see cref="T:genericclass<otherclass>" /> It will throw a Invalid referenceLink no matter what I do.

Second I would really really like my line endings and spaces in a <code> tag preserved. I guess there's a whitespace trim or something like that because this:

/// <code>
/// <configSections>
/// <section name="iDealConfiguration" type="iDeal.Configuration.iDealConfigurationSection"/>
/// </configSections>
/// <iDealConfiguration test="true" merchant="000001" returnUrl="" minimumAmount="98" communicationTimeout="2000"/>
/// </code>

Ends up like this(one big line):
<configSections><section name="iDealConfiguration" type="iDeal.Configuration.iDealConfigurationSection" /></configSections><iDealConfiguration test="true" merchant="000001" returnUrl="" minimumAmount="98" communicationTimeout="2000" />

Oops I got one more tiny issue:
Invalid referenceLink element.

Where do these come from?

Thanks again for all your efforts!

Jul 6, 2007 at 2:41 AM
Edited Jul 6, 2007 at 2:57 PM

First. When I have a parameter e that has e <see cref="T:genericclass<otherclass>" /> It will throw a Invalid referenceLink no matter what I do.

Use <see cref="T:genericclass{otherclass}"/> instead. Since angle brackets denote a tag in XML, it thinks you're trying to specify a tag without a closing tag. The curly braces are recognized by the compiler and Sandcastle as denoting a generic reference.

The tags in the code blocks are being treated as XML too. Sandcastle does strip all inter-element whitespace unlike nDoc which is unfortunate. The workaround for inline examples is to use HTML encoded angle brackets (&lt; and &gt;). However, a feature supplied by the help file builder's code block component allows you to import code from an external file using a source attribute (<code source="MyXMLFile.xml" lang="xml" />). When done this way, whitespace and line feeds are preserved. By the way, you'll want to start using lang attributes on the code tags for non-C# code blocks otherwise they'll all be colorized as C#. You can change the default behavior though using the configuration option. See the information on the Code Block Component in the help file for details.

Invalid referenceLink element

Does it tell you which reference link elements are invalid? It could be they are normal warnings and can be ignored but sometimes there have been bugs in the transformation files where stuff is missing or misspelled.

Jul 6, 2007 at 6:50 AM

Thank you for your swift response! I've solved BOTH my problems with you post. The 'src' attribute doesn't exist on the code element however. It's 'source', but the Help pointed it out to me so it didn't took me long to find out.

The 'Invalid referenceLink element' always appears after building the AllMembers part:
Info: BuildAssembler: Building topic AllMembers.T:iDeal.UI.iDealResponseRetrievedEventArgs`1
Warn: ResolveReferenceLinksComponent2: Invalid referenceLink element.

I've looked around in the created helpfile and couldn't find any abnormalities so I guess it works fine.

Thanks a bunch! I'm very happy with my documentation file!


Jul 6, 2007 at 2:56 PM
Edited Jul 6, 2007 at 6:59 PM
Thanks. I edited the post in case anyone reads it without going any further. Those warnings do occur often but can be ignored.