Problem with cross-reference links in HTML 1.x project (yet another "Unknown/Invalid reference link target" warning problem)

Topics: User Forum
Oct 9, 2009 at 11:32 PM

I'm using the May 2008 Sandcastle CTP with the corresponding November patches from Sandcastle Styles, along with SHFB 1.8.0.2.

I'm documenting a single VB.NET 2005 assembly with fairly complete comments and the usual VS-generated documentation XML file. However, when I compile the help file, none of my internal cross-references work -- they all show up as the plaintext

[Company.Product.TypeName]

instead of the linked version.

Doubtless, this is because of the warning pairs that show up in my log file, e.g.:

  Warn: CachedResolveReferenceLinksComponent: Unknown reference link target 'Company.Product.TypeName1'.
Warn: CachedResolveReferenceLinksComponent: Invalid reference link target 'Company.Product.TypeName1'.

(The same thing happens if I don't use the resolver cache component, it just builds 5-15 seconds slower.)

I've looked at the various topics on this forum, and can't figure out how to apply any of the suggestions to my situation. Or perhaps I should say, I've tried everything I could think of (using the Additional Reference Links plugin, adding the assembly under the References node, etc) and none of it has worked.

I really need the cross-references to work, and there's no good reason for them not to. Can someone please point me to some documentation that explains how to get cross-references to work?

Oct 10, 2009 at 12:01 AM

Clarification/addition: I'm using XML tags like this:

''' <returns>A <see cref="TypeName2" /> array containing... yada yada yada</returns>
''' <remarks>See also <seealso cref="TypeName1.MemberZ">MemberZ"</seealso>.</remarks>

and so forth.

I've tried qualifying the types by their full namespaces, and also removing all qualifications, but neither makes any difference.

Coordinator
Oct 10, 2009 at 10:51 PM

Help 1 isn't like Help 2 since the files don't get merged into a common collection.  As I recall, you need to either merge the two help 1 files into a single help file or use some other tools to allow such cross file links to work.  This has come up before but I couldn't find the related discussions.  You might try searching or posting in the MSDN Documentation and Help forum.  If it's an option you can build a help 2 file and set the project link type to index for both help files.  They'll work without any additional fixups.

Eric

 

Oct 10, 2009 at 11:01 PM

Hmmm... well, for one thing, I don't have the Help 2 compiler, and don't much feel like using that format, either -- the viewer requirements just aren't available in most places, and the integration doesn't seem to make sense. Maybe I'm looking at it wrong, but that's my take so far. (Forgot to check whether this problem occurs with Website format, though -- will check back shortly with that information.)

Another thing I should clarify is that these "cross-references" (perhaps an unfortunate choice of words?) aren't between two help files or two assemblies: there's only one assembly, one namespace, one Help 1 output file. So (I would think) everything would just work, since it's all in the same file. As it is, some references do work, like the auto-generated references to base classes or interfaces being implemented, but <see> and <seealso> references don't generate any links.

Does this ring any bells?

Coordinator
Oct 11, 2009 at 6:08 PM

Okay, this is a known issue with the VB.NET compiler.  It won't always generate fully qualified member names in the XML comments files.  There is no fix, only a workaround that involves you fully qualifying the class and member names in the cref attributes including the appropriate prefix (T:, P:, M:, etc).  See http://social.msdn.microsoft.com/Forums/en-US/devdocs/thread/a3e30d10-7de8-402c-a1d8-be883c87f3f2/ and http://shfb.codeplex.com/Thread/View.aspx?ThreadId=41016 and http://social.msdn.microsoft.com/Search/en-US/?query=VB%20compiler%20qualified&rq=meta:Search.MSForums.ForumID(faccaeb9-4c90-494e-b950-aba41d1547b1)&rn=Developer+Documentation+and+Help+System+Forum.

Eric

 

Oct 12, 2009 at 7:05 PM

Thanks! It works very nicely now, and all my references seem to be valid.