Guys

What is the best method to document the C# libraries rather than the XML documentation.

any idea?

__________________
--------------------
Thanks
Rose
[email protected]

From what I've found, the best way to document a C# code file is to use the XML documentation? What is wrong with using that?

You can easily "pretty up" the XML docs by creating an XSLT to make the XML into documents. There is a very good tool called NDoc that takes the XML docs from C# and makes them into MSDN style help pages in HTML and will compile the HTML into a compiled windows help file (.CHM) so you can get all your documentation in one file. It's very handy and looks good.

Allright Peter, sounds great... I remember that I asked a similar question some time ago, however it did not result in anything useful as far as I can remember. Therefor I started developing my own pretty-print parser, or rather XML reader, which would display the tree structure of classes and class members through an ASP page.

I stopped this project soon after I started since I noticed that the output gathered in the XML document is rather minimal. I cannot recall exactly what I found missing, except from e.g. access modifiers as private, public. So if I wanted to continue I had to parse the source files before I could display the documentation, and that was more than I wanted to do!

So what I am hopeing for is a better extraction of data from the source files; i.e. different properties of classes, methods and members of these (types, access modifiers etc). Possibly user defined tags!

Jacob.

Peter's suggestion, NDoc, is really great.

Much of what you require is offered by NDoc. Take a look here: http://sourceforge.net/projects/ndoc/

To get a feel of how it will look (also compared against the VS.NET documentation feature), look at the last image in this article:
http://www.squiffler.com/squiffler/article.aspx?id=1

You can also check out some other articles about NDoc from their articles page: http://ndoc.sourceforge.net/wiki/NDoc_Articles

IMO, it's worth a try. With my previous employer, we used it for documentation as much as possible.

Cheers,

Imar


---------------------------------------
Imar Spaanjaars
Everyone is unique, except for me.

It sounds great, but does it extract the XML comments and documentation from the source code, or is it based on the XML extraction done from within VS.NET? Does it extract the access modifier aswell?

Thanks

Jacob.

The C# compiler takes the XML documentation from the source files and creates the XML file that you'll find next to the compiled DLL. NDoc uses that PLUS reflection of the classes from the compiled DLL to create the full documentation. Take a look at the docs online for a class library I created. Those docs are created with NDoc. If you download the library with the full source you can see the XML comments in the C# code. Compare those with the docs and you'll see how it's merged together with the info from reflection. NDoc generates the detail regarding stuff like member accessibility/scope for you.

Peter
------------------------------------------------------
Work smarter, not harder.

It uses the XML file generated by VS.NET, but it does dig deeper in assemblies to get additional info.

Not sure how it deals with access modifiers. I usually only document public stuff..... Maybe you should check it out. It's really simple to set up and use. All you need to do is download it, open te .sln file and run it. Then point to the Bin folder of your app (it will automatically recognize the associated .xml file) and off you go.

Imar


---------------------------------------
Imar Spaanjaars
Everyone is unique, except for me.

Coool! That was just what I wanted; that is, that the program (NDoc) not only use the XML documentation generated by VS.NET, but also extract other information! It then covers what I found missing the last time I used it. It looks great...

Thanks for answering this long forgotten thread. Thanks! :)

Jacob.