see and cref

Topics: User Forum
Dec 6, 2006 at 3:14 PM
I need some help with using the <cref> documentation tag within c++. While trying to document the first class, I am trying to reference a second class within the same namespace. For example:

MyNamespace:
MainClass
DocumentThisFuncion()
HelperClass.

I have tried the following three approaches but always get a compiler warning that the xml references an “unknown symbol”.

//Try one:
///<summary>Documenting DocumentThisFunction.
/// For additional information look at <see cref=”HelperClass” />
///</summary>

//Since that didn’t work, try this one:
///<summary>Documenting DocumentThisFunction.
/// For additional information look at <see cref=”MyNamespace.HelperClass” />
///</summary>

//No luck so try
///<summary>Documenting DocumentThisFunction.
/// For additional information look at <see cref=”M:Namespace.HelperClass” />
///</summary>

Can someone point out where I am going wrong?

Thanks.
Coordinator
Dec 6, 2006 at 8:54 PM
This appears to be a "forward reference" issue with the C++ compiler. Because it hasn't seen the class yet, it warns you that it doesn't exist. I tested it out and the XML comments file appears to be generated correctly even when this occurs. You can suppress the warning in question with a "#pragma warn" statement or through the project options.

Eric
Coordinator
Dec 7, 2006 at 4:46 PM
I'm working on another problem related to C++ XML comments and noticed that I was wrong in my prior post. It doesn't generate a correct reference to the member in the warning. It's compiler related so you'll have to ask in the C++ or documentation forum on MSDN to see if there is a workaround. It's been a long time since I worked with C++ and haven't used Managed C++ at all so I don't know of a solution to this problem.

Eric