C# XML Doc Tags

  • Thread starter Thread starter Michael Taylor
  • Start date Start date
M

Michael Taylor

Maybe it's me but I can't get several of the
documentation tags to work. They are added verbatim to
the generated comment webpage even though the links are
accurate.

I can't get paramref, see and seealso to work.
Furthermore when viewing the members of an enumeration
the link back to the parent type is wrong.

Does anybody else have this problem? The concept is cool
but it doesn't seem to work correctly.

BTW, this happens on 2 different machines using both my
own code and samples from MSDN and the Web. I'm using
VS .NET 2003. The steps I take are:

1) Create a project with the comments
2) Compile the solution
3) Build the comment webpage from the Tools menu

Thanks,
Michael Taylor - 7/21/03
 
3) Build the comment webpage from the Tools menu

Michael -
I've never seen the problem that you're describing, but I have a tool
that might help. Check out NDoc (http://sourceforge.net/projects/ndoc). You
probably want to download the last stable release which is ndoc-installer
(ndoc v1.1c). NDoc is an open source tool which can build MSDN style or
JavaDoc style help files. (It can also make LaTeX and Xml files for those
who want a more custom solution.) It has a whole slew of options you can
turn on or off to customize your documentation. I find it to be a much
better tool for building documentation than the VS.NET build-in documenter
which produces what I feel is a less-than-user friendly help file.

Just my two cents. Although I'm sure you'd like to get the VS.NET issue
resolved as well. ;-)
 
Actually I'm playing around with NDoc but I want to make sure the comments
in the code are correctly generated before I get to far. Thanks.

Michael Taylor - 7/21/03
 
I LOVE ndoc. I use it every time I write an app.
Documenting before C# was a PITA. With C# XML comments it
is much less a drag - but I don't like the built in
documentor. nDoc makes your code documenting much more
professional looking, IMO. Because of how nDoc makes my
documentation look (I prefer MSDN style), it encourages me
to document my code more thoroughly.
-----Original Message-----

Michael -
I've never seen the problem that you're describing, but I have a tool
that might help. Check out NDoc
Click to expand...
(http://sourceforge.net/projects/ndoc). You
 
professional looking, IMO. Because of how nDoc makes my
documentation look (I prefer MSDN style), it encourages me
to document my code more thoroughly.
Click to expand...

I agree. I was very surprised that VS.NET didn't make MSDN style
documentation by default. Seemed like the natural thing to do.

Michael - Are the help files NDoc is making not linking properly (the
parmref, see, and seealso tags) or is it just the comments pages that VS.NET
is producing? You can set it up to make the Xml documentation output and
then just run NDoc on that - you don't need to have the step "Build Comment
Webpages" unless you want to use the format that VS.NET makes.
 
I had some problems with the built-in VS 2002 comment generator.
Seems like see or seealso were problematic. I just use ndoc
exclusively because it seems to work better (besides having nicer
formatting).

mike
 
Back
Top