XML tags and /doc switch

[Ken Allen]

I came across the reference to the self-documenting comment tags that can be
embedded in the C# source code (e.g., ///<summary>) and used to generate an
XML file that describes the code. This looks interesting, but I have some
concerns.

1. If I enable this for a single project, add some tags for most objects,
specify the XML output file name, then I can build the project with no
problems and the XML file is created -- but if I attempt to build the
solution it complains that not all of the members of every structure I
defined have a tag associated with them! Why this discrepency and how do I
convince the solution build to permit this?

2. I am permitted to enter the name of the XML file to generate, but I
cannot put a relative path in front of the name -- if I do then the "Apply"
button erases the text that I entered.

3. Is there some facility available that will convert the genersted XML into
a documentation dictionary? The XML file is cool, but I do not see it as
being much use outside of the IDE itself.

4. The documentation indicates that the commentes entered are used for
intellisense and the object browser displays -- do I have to generate the
XML file to get these beefits, or merely define the tags?

-Ken

 

[n!]

1. If I enable this for a single project, add some tags for most objects,

specify the XML output file name, then I can build the project with no
problems and the XML file is created -- but if I attempt to build the
solution it complains that not all of the members of every structure I
defined have a tag associated with them! Why this discrepency and how do I
convince the solution build to permit this?

They are only warnings, you can ignore them if you wish. The compiler is
complaining because you've stated you want documentation, but you haven't
documented your publicly accessible objects. Which means the documentation
will be incomplete. You don't need to document *all* classes\methods, only
publicly accessible ones. So mark classes that you don't intend to be
accessed from elsewhere 'internal'. The same goes for methods\properties
etc, mark them private or internal as required.

3. Is there some facility available that will convert the genersted XML into
a documentation dictionary? The XML file is cool, but I do not see it as
being much use outside of the IDE itself.

I use ndoc (http://ndoc.sourceforge.net) which is excellent (erm, if that
link doesn't work try searching for ndoc on sourceforge. Our http web access
is currently broken and I can't verify I remembered it correctly).

4. The documentation indicates that the commentes entered are used for
intellisense and the object browser displays -- do I have to generate the
XML file to get these beefits, or merely define the tags?

You need to give the tags a body if you actually want them to display
something. The XML file is used for class libraries that are not a part of
your project but are referenced by your assembly (IIRC).

n!