C# XML Doc Tags

[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

[Kevin Conroy]

> 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. ;-)
--

Kevin Conroy, Programmer

[Michael Taylor]

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

"Kevin Conroy" <kc******@prolist.com> wrote in message
news:%2****************@TK2MSFTNGP11.phx.gbl...

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. ;-)
--

Kevin Conroy, Programmer

[JKJ]

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

3) Build the comment webpage from the Tools menu
Michael -
I've never seen the problem that you're describing,

but I have a toolthat might help. Check out NDoc (http://sourceforge.net/projects/ndoc). Youprobably 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 orJavaDoc style help files. (It can also make LaTeX and Xml files for thosewho want a more custom solution.) It has a whole slew of options you canturn on or off to customize your documentation. I find it to be a muchbetter tool for building documentation than the VS.NET build-in documenterwhich 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 issueresolved as well. ;-)
--

Kevin Conroy, Programmer
.

[Kevin Conroy]

> professional looking, IMO. Because of how nDoc makes my

documentation look (I prefer MSDN style), it encourages me
to document my code more thoroughly.

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.

--

Kevin Conroy, Programmer

[Michael Mayer]

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