Source code documentation

G

GTi

Is there any source code documentation tools available for Visual
Studio 2005 ?
I have created a LIB that must be documented. Must I do it by hand or
is it
some kind of tools to pre document my source code?
 
G

Guest

Hi GTi,
I was looking into the issue a few weeks ago. From what I found NDoc at
present only has partial support for .Net 2.0, doesn't seem to be any
definitive date on when it will have full support. The only other option I
found was a company called Inovasys (www.innovasys.com) who have a product
called Document X which will be fully compable with 2.0 by then end of this
month. At the moment they do have a beta but it is only available to
existing companies. So if you can wait a few weks this may be worth checking
out. It is a commercial product so it is not free if that is one of your
main criteria.

Hope that helps
Mark Dawson
http://www.markdawson.org
 
C

Christoph Nahr

There is built-in XML Documentation Comment support in Visual Studio.Net
2005.
Click to expand...

There is!? Where? I was firmly convinced that this 2003 feature was
taken out of 2005 -- can you tell me the exact menu location?
 
M

Michael Nemtsev

Hello Christoph,

Kevin means that you can get XML documentation, not the chm compiled as NDoc
did.
To turn this on go to the project properties->Build panel-> check "XML Documentation
file"

to be shure that every method/class has been documented check "treat warnings
as error" on ALL

CN> On Sat, 4 Mar 2006 10:25:52 -0500, "Kevin Spencer"
CN> There is!? Where? I was firmly convinced that this 2003 feature was
CN> taken out of 2005 -- can you tell me the exact menu location?
CN>
---
WBR,
Michael Nemtsev :: blog: http://spaces.msn.com/laflour

"At times one remains faithful to a cause only because its opponents do not
cease to be insipid." (c) Friedrich Nietzsche
 
G

Guest

Are you saying the option in VS2003 Tools->Build Comment Web Pages has been
taken out is VS2005? Wow, I did not know that.....pretty disappointing.
 
K

Kevin Spencer

Are you saying the option in VS2003 Tools->Build Comment Web Pages has
been
taken out is VS2005? Wow, I did not know that.....pretty disappointing.
Click to expand...

It's not really disappointing if you think about it. If you create HTML Code
Comments, you have created an HTML document. Modifying it to suit your own
model of how it should look is a pain in the butt. HTML is simply *not*
extensible.

But if you create XML Code Comments, you can create *any* type of document
from the XML, simply by creating an XSL Transform for it. You can transform
it in any way you like, and change the format with a simple change to the
XSLT that you use to format it. That is what I did in the page I mentioned
earlier in the thread. I created my own XSLT and use it for all of our
in-house code documentation.

This is part of the "new direction" that Microsoft has been taking, and I
welcome it!

--
HTH,

Kevin Spencer
Microsoft MVP
..Net Developer

Presuming that God is "only an idea" -
Ideas exist.
Therefore, God exists.
 
W

William Stacey [MVP]

I installed a version of NDoc for 2.0 and it does everything in 2005 AFAICT.
Docs look great. What does it not support?

--
William Stacey [MVP]

| Hi GTi,
| I was looking into the issue a few weeks ago. From what I found NDoc at
| present only has partial support for .Net 2.0, doesn't seem to be any
| definitive date on when it will have full support. The only other option
I
| found was a company called Inovasys (www.innovasys.com) who have a product
| called Document X which will be fully compable with 2.0 by then end of
this
| month. At the moment they do have a beta but it is only available to
| existing companies. So if you can wait a few weks this may be worth
checking
| out. It is a commercial product so it is not free if that is one of your
| main criteria.
|
| Hope that helps
| Mark Dawson
| http://www.markdawson.org
|
|
| "GTi" wrote:
|
| > Is there any source code documentation tools available for Visual
| > Studio 2005 ?
| > I have created a LIB that must be documented. Must I do it by hand or
| > is it
| > some kind of tools to pre document my source code?
| >
| >
 
G

Guest

I don't think you understood what I said. That is not what I found
disappointing.

In VS 2003, you could use the inline XML Comments to document your code in
the source code files. The compiler would read these XML comments and
generate an XML document with this information. Now VS 2003 had a built in
tool to read this XML Document, and generate an MSDN like web page that has
your code documented.

The idea was, "We have a tool to interpret the XML document and display it
in a web page to document your code. If it does not suit your needs, then
use NDoc or write your own tool (XSLT, etc) to suit your needs."

Now, in VS 2005, the compiler still generates the XML Document and that's
it. Now the idea is "Here's the XML document, now write your own tool to do
as you wish. We will no longer give you a tool do generate a page for you.
You have to do it yourself." And now as an other user stated, NDoc does not
fully support .NET 2.0 XML code genreated comments (I'll have to look into
this to see if this is true).

What I found disappointint is that they took a tool away that reads the XML
Comment document for you. Most of the time, it suited my needs
 
M

Michael Nemtsev

Hello rmacias,

Where have u found this option? Could you point? I see nothing in my VS 2003

r> Are you saying the option in VS2003 Tools->Build Comment Web Pages
r> has been taken out is VS2005? Wow, I did not know that.....pretty
r> disappointing.
r>
r> "Michael Nemtsev" wrote:
r>---
WBR,
Michael Nemtsev :: blog: http://spaces.msn.com/laflour

"At times one remains faithful to a cause only because its opponents do not
cease to be insipid." (c) Friedrich Nietzsche
 
G

Guest

It's in the "Tools->Build Comments Web Page" option. I've using VS 2003
Enterprise Developer. The option should be there. It only works with C#
though.

I did a little googling and found out that many customers didn't like it and
it was cut from VS2005. I'll have to find another tool to create my
documentation sites now. The tool in VS2003 suited my needs well. That's
too bad.
 
G

Guest

I agree with you rmacias, the tool provided in 2003 was more than adequate
for code comments, taking it out in my mind was a great loss, especially if
people are expected to rely on group projects such as NDoc which seems to be
slow in catching up.
 
G

Guest

NDoc v1.3 does not support Generics. The nightly build does have generics
capability but is still in alpha.....apparently.
 
M

Michael Nemtsev

Hello rmacias,

Got it. I just have never use it :)

I recomend to look at GhostDoc http://www.roland-weigelt.de/ghostdoc/ it
works for VS2005

r> It's in the "Tools->Build Comments Web Page" option. I've using VS
r> 2003 Enterprise Developer. The option should be there. It only
r> works with C# though.
r>
r> I did a little googling and found out that many customers didn't like
r> it and it was cut from VS2005. I'll have to find another tool to
r> create my documentation sites now. The tool in VS2003 suited my
r> needs well. That's too bad.
r>
r> "Michael Nemtsev" wrote:
r>---
WBR,
Michael Nemtsev :: blog: http://spaces.msn.com/laflour

"At times one remains faithful to a cause only because its opponents do not
cease to be insipid." (c) Friedrich Nietzsche
 
C

Christoph Nahr

I installed a version of NDoc for 2.0 and it does everything in 2005 AFAICT.
Docs look great. What does it not support?
Click to expand...

The "a version" you installed was either an alpha test release, or a
modification by another user. There is no public release of NDoc 2.0
on the SourceForge website yet!
 
C

Christoph Nahr

But if you create XML Code Comments, you can create *any* type of document
from the XML, simply by creating an XSL Transform for it. You can transform
it in any way you like, and change the format with a simple change to the
XSLT that you use to format it. That is what I did in the page I mentioned
earlier in the thread. I created my own XSLT and use it for all of our
in-house code documentation.
Click to expand...

That's not what anyone thinks of when you say Visual Studio has
"built-in XML Documentation Comment". Please mention additional
custom tools that you're using, we can't read your mind...
 
M

Michael Nemtsev

Hello Christoph,

What do u mean with "additiona custom tools" ?!
Kevin just opened notepad, wrote XSLT schema for VS XML Doc file and he got
a formatted HTML with documented code

CN> On Sat, 4 Mar 2006 15:58:19 -0500, "Kevin Spencer"
CN> That's not what anyone thinks of when you say Visual Studio has
CN> "built-in XML Documentation Comment". Please mention additional
CN> custom tools that you're using, we can't read your mind...
CN>
---
WBR,
Michael Nemtsev :: blog: http://spaces.msn.com/laflour

"At times one remains faithful to a cause only because its opponents do not
cease to be insipid." (c) Friedrich Nietzsche
 
C

Christoph Nahr

The XSLT schema that Kevin wrote is a custom tool, and so is the XSLT
processor that he used to generate his web pages.
 
K

Kevin Spencer

My custom-built "tool" is simply an XSLT file.

--
HTH,

Kevin Spencer
Microsoft MVP
..Net Developer

Presuming that God is "only an idea" -
Ideas exist.
Therefore, God exists.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Similar Threads

System.Collections.Generic.IList<MicroLite.SerialNumber>' is lessaccessible than method 1
XML doc tool 3
Adding source files from outside directory WITHOUT them being copiedto the projectdirectory 5
retro conversion to VS2003 3
An open source Tortoise SVN AddIn for Visual Studio 2
I am beginner 1
MS Access - Form - Upload document to Sharepoint Server (whoes folder is mapped to my PC) from Acce 0
Autogenerating documentation from the c# source code comments 3

Top