Some .NET XML documentation tags are not recognized when I update my solution's documentation

[Will Pittenger]

I have a Windows program C# .NET solution where when I update its XML
documentation, some tags are not recognized and turned into the
corresponding HTML. Those tags include <c>, <code>, <para>, <paramref>, and
<exception>. <remarks> works; I have not tried <include>. Is this a bug in
Studio or am I using those tags incorrectly?

When the tag appears to have an attribute, I have tried
<paramref="parameter">paramter name</paramref> and the way that autocomplete
completes the tag: <paramref=">parameter"/>. Since neither works, which is
correct? What, if anything, am I doing wrong?

 

[Joerg Jooss]

I have a Windows program C# .NET solution where when I update its XML
documentation, some tags are not recognized and turned into the
corresponding HTML. Those tags include <c>, <code>, <para>,
<paramref>, and <exception>. <remarks> works; I have not tried
<include>. Is this a bug in Studio or am I using those tags
incorrectly?

When the tag appears to have an attribute, I have tried
<paramref="parameter">paramter name</paramref> and the way that
autocomplete completes the tag: <paramref=">parameter"/>. Since
neither works, which is correct? What, if anything, am I doing wrong?

Other than using the wrong tool... nothing ;-)

It's sorry that this particular feature of VS .NET is rather useless,
because it just does not support all the tags (for whatever reason). Switch
to NDoc, which is free and vastly superior: http://ndoc.sourceforge.net/wiki

Cheers,

 

[Will Pittenger]

So, why doesn't Microsoft's documentation match what Microsoft actually
supports? Does this other package use the same tags and work from within
VS?

 

[Michael Mayer [C# MVP]]

NDoc iks not integrated with VS (to my knowledge) but it does support the
tags that Microsoft defined (<c>, <para>, <list> etc)

You can create an NDoc project file (*.ndoc), and then add that file to your
visual studio solution. If you then tell VS to associate that NDoc project
file with the NDoc executable, you can just double click the ndoc file in VS
and it will open NDoc for you. Hit the "build" button in ndoc and it will
build help for you - only one more step than what you currently are doing.

The resulting help files can be integrated with visual studio:
http://www.reflectionit.nl/NDoc.aspx

As for why MS doesn't support their own documentation, my guess is
resources. I suppose that they had big plans but didn't have the time to
make it all happen (but at least they got the important part of the xml
comments and defining set syntax). NDoc came along and made it happen, so
there isn't as much reason for MS to reinvent the wheel (not that they
haven't done that before).

 

[Will Pittenger]

Well, I have suspected for several years that Microsoft always has a
"super-duper" build system that they keep to themselves. Everything works
and is better thought out. They certainly put their favorite goodies into
their own products before making them available in MFC, Win32, or .NET. As
an example, notice that Office does not follow your XP skin (or WindowBlinds
skin for that matter). You can get the look offered by the toolbar buttons
for buttons, button-style checkboxes, and button-style radio buttons, but
not in the .NET or MFC toolbars. In order to get AutoComplete to see new
classes and/or new members of classes, I commonly have to restart VS.

Microsoft's not supporting those tags may be more of the same. They
probably even claim they are helping 3rd party add-in developers out.

 

[Will Pittenger]

I was just looking at NDoc's website. From what I can tell, I might have to
build their project to install it. Second, in order to see updated
documentation, you must be able to build with no errors. Third,
IntelliSense does not help with the NDoc extensions to the tags. Fourth,
some hand coding of XML is required. (I have never worked directly with
XML.)

 

[Joerg Jooss]

I was just looking at NDoc's website. From what I can tell, I might
have to build their project to install it.

Come on, you're a developer ;-)
But there's no need to do that. Go to the project's page on SourceForge and
download a stable package (ndoc-devel-v1.2.zip):

http://sourceforge.net/project/showfiles.php?group_id=36057

If you want t create .chm help files, you will also need to install MS HTML
Workshop, which can be downloaded from MSDN or should be coming with your
version of VS .NET.

Second, in order to see
updated documentation, you must be able to build with no errors.

I'm not sure whether this an NDoc limitation -- the C# compiler produces all
necessary output for document generation.

Third, IntelliSense does not help with the NDoc extensions to the
tags.

Correct, but nothing forces you to use them.

Fourth, some hand coding of XML is required. (I have never
worked directly with XML.)

Well, you do work with C# XML comments already, don't you? Anyway, for basic
documentation generation, NDoc should work out-of-the-box if you stick to
the original comment tags you already know.

Cheers,

 

[Will Pittenger]

With Microsoft's documenter, you can update the documentation from the Tools
menu without building.

 

[Will Pittenger]

Have you posted projects with NDoc specific tags to CodeProject? While
other users might not have a problem with the compiled project, they may be
unable to build the help system. I did want to post my project when I am
done.