How to make forward reference cref in C++/CLI

Aug 17, 2008 at 9:25 PM
How can I make a reference in eg. a <see cref="..."/> to a method that has not yet been declared in C++?
Consider for example the following scenario:

public enum class Color
{
/// <summary>
/// Red color. Used with <see cref="M:Window::SetColor" />.
/// </summary>
Red,
/// <summary>
/// Blue color. Used with <see cref="M:Window::SetColor" />.
/// </summary>
Blue
};

public ref class Window
{
public:
/// <summary>
/// Changes the color to the one specified. See also <see cref="Color" />
/// </summary>
void SetColor(Color color);
};
The reference in the documentation from Window to the enum will work, but it seems the reference from the enum to the method in the class will not. And I don't see how I can create a forward declaration in C++ that would allow this?
Is there a solution to this?
Aug 18, 2008 at 4:16 AM
Edited Aug 18, 2008 at 4:21 AM
Hello,
I have tried some few ways without a success - at least not yet!

I do not if there is a solution to this using the current C++/CLI compiler.
If you do  not find any means of getting it done, then this is one approach...
  1. Use the expected generated link, with a dummy, dref attribute:
    <see dref="M:SomeNamespace.Window.SetColor(SomeNamespace.Color)" />
  2. Open the generated XML file and replace, dref with cref.
  3. Compile the help file as usual, you will loose the C++/CLI verification of links but Sandcastle
    will give you warning if the links are not valid.

If there is no better solution, I will consider supporting the dref (call it direct reference) in an update
to the link resolving component I am working on, so that you do not have to find and replace it.

Best regards,
Paul.

Editor
Aug 18, 2008 at 4:45 AM
No need for a component.  You could just update the Sandcastle transformations to handle "dref" as well as "cref" in the same way.

Eric
Aug 18, 2008 at 5:24 AM
>>EWoodruff: You could just update the Sandcastle transformations to handle "dref" as well as "cref" in the same way.
Sounds better, we could distribute it with the Sandcastle Styles.
Lets wait and see if a better solution could be found, if not we update the Sandcastle Styles to handle it.

Best regards,
Paul.
Aug 21, 2008 at 5:05 PM
Thanks, this approach works just fine! =)
Editor
Aug 21, 2008 at 7:43 PM
Edited Aug 21, 2008 at 7:44 PM
I don't know if you saw it, but somebody pointed out on the SHFB forum that if you set the CppCommentsFixup project property to true, it will automatically fix up the invalid cref arguments.  I put that in a while ago and had forgotten that it was there.

Eric