Re: XML tags and /doc switch

From: n! (nfactorial_at_nomailplease.com)
Date: 04/15/04 

Date: Thu, 15 Apr 2004 17:17:08 +0100

> 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!

Relevant Pages

  • Novice - trying to get started with docbook
    ... This is my first attempt at XML documentation. ... I'm trying to get started with docbook so I can put a set ... Netscape simply displays the xml tags, ...
    (comp.text.xml)
  • Re: SV: Creating a list of TODOs
    ... VS doesn't really have a facility for this, unless you count XML comments. ... Almost all tools out there that process XML documentation are flexible enough to allow you to specify your own tags and how they should be processed, so there's little competition going on, really. ... However, XML comments are flexible enough that you can actually do this without much fuss -- if you often need to cooperate with other developers on code that's incomplete, for example, <todo> might come in handy. ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: Code documentation.
    ... >> because all documentation tools use the same general syntax so a more ... XML has the advantage of being more easily ... I do agree that the c# way is easier to parse for a _program_. ... small hack that parse the documentation tags that has been in use for decades ...
    (microsoft.public.dotnet.general)
  • Re: Some .NET XML documentation tags are not recognized when I update my solutions documentation
    ... > I have a Windows program C# .NET solution where when I update its XML ... > documentation, some tags are not recognized and turned into the ... because it just does not support all the tags. ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: Getting NASM from C
    ... > format we were going to edit it in... ... all XML is? ... HTML is a specific "subset" of XML for displaying ... it's a text file with "tags" inside ...
    (alt.lang.asm)