Wrox Programmer Forums
Go Back   Wrox Programmer Forums > .NET > .NET 1.0 and Visual Studio.NET > VS.NET 2002/2003
|
VS.NET 2002/2003 Discussions about the Visual Studio.NET programming environment, the 2002 (1.0) and 2003 (1.1). ** Please don't post code questions here ** For issues specific to a particular language in .NET, please see the other forum categories.
Welcome to the p2p.wrox.com Forums.

You are currently viewing the VS.NET 2002/2003 section of the Wrox Programmer to Programmer discussions. This is a community of software programmers and website developers including Wrox book authors and readers. New member registration was closed in 2019. New posts were shut off and the site was archived into this static format as of October 1, 2020. If you require technical support for a Wrox book please contact http://hub.wiley.com
 
Old March 26th, 2004, 03:22 PM
Authorized User
 
Join Date: Aug 2003
Posts: 20
Thanks: 0
Thanked 0 Times in 0 Posts
Send a message via Yahoo to rosalynb
Default best way to document the C# libraries

Guys

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

any idea?
__________________
--------------------
Thanks
Rose
Anirose_us@yahoo.com
 
Old March 29th, 2004, 05:20 PM
planoie's Avatar
Friend of Wrox
 
Join Date: Aug 2003
Posts: 5,407
Thanks: 0
Thanked 16 Times in 16 Posts
Default

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.
 
Old March 29th, 2004, 06:29 PM
Friend of Wrox
 
Join Date: Jun 2003
Posts: 440
Thanks: 0
Thanked 0 Times in 0 Posts
Default

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.
 
Old March 30th, 2004, 04:35 AM
Imar's Avatar
Wrox Author
 
Join Date: Jun 2003
Posts: 17,089
Thanks: 80
Thanked 1,576 Times in 1,552 Posts
Default

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.
 
Old March 30th, 2004, 11:33 AM
Friend of Wrox
 
Join Date: Jun 2003
Posts: 440
Thanks: 0
Thanked 0 Times in 0 Posts
Default

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.
 
Old March 30th, 2004, 11:48 AM
planoie's Avatar
Friend of Wrox
 
Join Date: Aug 2003
Posts: 5,407
Thanks: 0
Thanked 16 Times in 16 Posts
Default

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.
 
Old March 30th, 2004, 12:00 PM
Imar's Avatar
Wrox Author
 
Join Date: Jun 2003
Posts: 17,089
Thanks: 80
Thanked 1,576 Times in 1,552 Posts
Default

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.
 
Old March 30th, 2004, 12:05 PM
Friend of Wrox
 
Join Date: Jun 2003
Posts: 440
Thanks: 0
Thanked 0 Times in 0 Posts
Default

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.





Similar Threads
Thread Thread Starter Forum Replies Last Post
Kodak Libraries dmoorejr VB Components 5 August 5th, 2011 03:24 AM
Class Libraries SamsDaddy BOOK: Beginning Visual Basic 2005 ISBN: 978-0-7645-7401-6 4 April 18th, 2006 10:36 AM
static libraries silvia C# 3 March 2nd, 2006 04:50 AM
Reference Libraries Bob Hansen BOOK: Expert One-on-One Access Application Development 8 October 5th, 2004 03:28 PM
libraries riteshu C++ Programming 1 October 4th, 2004 06:44 PM





Powered by vBulletin®
Copyright ©2000 - 2020, Jelsoft Enterprises Ltd.
Copyright (c) 2020 John Wiley & Sons, Inc.