Jan Schreuder on .Net

.Net code samples, experiences, observations

View my professional profile on LinkedIn

Recent Posts

Tags

News

  • Inappropriate comments will be deleted at my discretion.

    The information and code samples in this weblog is provided "AS IS" without warranty of any kind, either expressed or implied, including but not limited to the merchantability and/or fitness for a particular purpose.

Community

Email Notifications

Tool suppliers

Tools

General

Microsoft

Favorite blogs

Archives

Generate documentation for .Net 2.0

As we all know, C# (and VB.Net 2.0) give you the option of adding XML documentation tags to your code. And as professional developers, we all use this option to document the code. At a certain point, you may need to generate a help file for assemblies you wish to distribute. I myself own a library which I distribute amongst my colleagues and for the .Net 1.1 version, I used NDoc 1.3 to generate the documentation. This week, I finally found time to finish the migration of the library to .Net 2.0. I replaced the delegates I used for events for the generic version, removed objects that were obsolete due to new stuff in .Net 2.0, and cleaned up the code using FxCop 1.35. But then came the task of generating the documentation for the library before distributing the new version. And that's where I ran into trouble.

First of all, the most recent version of Ndoc (1.3), does NOT support .Net 2.0. I checked the NDoc pages on SourceForge, but only found a version from june 2005 which didn't work. Links on that page to more information about generating documentation for .Net 2.0 didn't work either. I then proceeded to google for a new version of NDoc. One of the things I found was that the original developer of NDoc is not really working on that project anymore because of health problems. I hope he well recover soon.

I also found loads of alpha's, beta's and other versions which all claim to work. Unfortunately I haven't yet been able to get any of these versions working. They all have one or more problems, or unknown dependencies, which are working against me. So if you're reading this, and have a version of NDoc which I can install and that works, please respond to this post.

I found the following threads on http://forums.microsoft.com/MSDN which pointed me to the beta's I mentioned above:

When you read those threads, you will find responses from Microsoft employees. And those responses are very interesting, as you can see from the following quote:

26 May 2006, 12:25 AM UTC

As I mentioned in the other thread our plans are to release documentation compilers for .Net 2.0 as a Community Technology Previews (CTP) version by the end of June 2006 and then RTM by the end of August 2006. I will have a detailed post about this before our CTP release next month. Cheers.

Anand. Microsoft Corporation

Group Manager, Developer Division

This is of course really interesting. Apparently, Microsoft will release a CTP version of a documentation compiler somewhere this month. Let's hope they do. All I want is a simple way to generate my documentation again. If it's a new version of NDoc, great. If it's the new Microsoft stuff, fine. I'll keep y'all posted!

Posted: Fri, Jun 16 2006 8:41 AM by Jan Schreuder | with 15 comment(s)
Filed under: ,

Comments

Ramon Smits said:

I am using a version found through the ndoc main site. But the documents that hold the link aren't served at the moment. Will get back to you on the version I am using at home.
# June 16, 2006 3:42 AM

P.J. van de Sande said:

Don't forget to install GhostDoc as well. But for the .NET 2.0 support, here is a quote of the persistents:

NDoc 1.3 can document .Net 2.0 assemblies if an app config file is supplied to force NDoc to prefer the 2.0 framework over the 1.1 framework

You can download a zip file containing example config files from here. Just place the config files in the same directory as the NDoc binaries, and you are ready to go :)

If you have a different version of the 2.0 framework such as that which is supplied with the latest C# Express beta, then you will have to update the version number within the file - it should be obvious where to make the change once you have looked at the file contents... VS 2005 Beta 2 needs this tag <supportedRuntime version="v2.0.50215" /> ... VS 2005 RTM needs this tag <supportedRuntime version="v2.0.50727" />

Note, however, that generics are *not* supported, nor is importing VS.NET 2005 solutions.

If you use NDoc to document an assembly containing generics the results will be, at best, disappointing - it is quite likely that NDoc may abend or produce output that cannot be compiled by the help compilers...

? The generated framework links use the 1.1. framework namespace. Do we need to wait until the Alpha version to have an NDoc that will generated links to the 2.0 framework topics?

Whilest waiting for the final 2.0 version of NDoc; a modified version of NDoc 1.3.1 that is compiled with support for generics can be found here. This version produces decent output for generics but doesn't handle links to system types.


I see the page is offline at the moment, but you can view it yourself in the google cache. With working links:
http://66.249.93.104/search?q=cache:LmKSsFUd680J:ndoc.sourceforge.net/wiki/dotNet_2.0_Support+ndoc+2.0+support&hl=en&ct=clnk&cd=1
# June 21, 2006 2:33 AM

Jan Schreuder said:

Yep, I use Ghostdoc as well. A really good help when you want to add XML tags to your code.

There is a beta version of NDOC for VS 2005 at sourceforge: http://sourceforge.net/projects/ndoc05. The latest build is date somewhere in April 2006. But I can't get it to work. Anyone have any clues?
# June 21, 2006 3:29 AM

Ramon Smits said:

The problem with ndoc is that is generated default documentation. Documentation that a developer really doesn't need because it does not add more information.

The documentation elements are only very usefull for describing a methods funcionality in detail with remarks and examples.

If you cannot provide that information then you can better not add xml documentation at all.
# June 23, 2006 12:42 AM

Jan Schreuder said:

Sounds obvious Ramon. Ofcourse you need to add remarks and examples. It's what I do in my code library. And if a developer cannot provide that information, than why is he/she wrting the code in the first place?
# June 23, 2006 5:10 AM

Ramon Smits said:

Well it depends on the complexity of a method. There are alot of methods that really don't need any documentation. For example a stack object which has a Push and Pop method.
# June 23, 2006 6:38 AM

Jan Schreuder said:

If some methods are that obvious, then why would Microsoft bother to document every single property and method in the System.IO namespace? For example, the File.Copy method. Pretty obvious what it will do, right? Try this link: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemiofileclasscopytopic.asp

Overkill? I think not. Even obvious stuff needs documentation. If not for its purpose, then at least for examples, exceptions, etc.
# June 23, 2006 12:38 PM

Ramon Smits said:

Yes you are correct but I was referring to the documentation that ghostdoc generates. As you have seen even the simplest of documentation on this method couldn't be genereted by ghostdoc :). Examples, exceptions and remarks still have to be added by hand.

We use some logic in our documentation task of our build server to detect if documentation is usefull. Not that is does extremely difficult stuff. It currently just checks default content and return value documentation. We opt for manually added documentation on all properties, methods, classes, interfaces, etc. and on all visibility types (public, internal, protected, etc.).

I really think it's overkill in general. I like a good general class description and some good examples at class level. But that is just my prefered documentation style because I also browse for documentation this way. I use intellisense, get to the class and smash F1 ;)
# June 23, 2006 2:25 PM

Ravi Bhavnani said:

I've been using this version of NDoc for .NET 2 for some time.  Works quite well.

http://jonas.lagerblad.com/blog/?p=4

/ravi
# June 28, 2006 7:43 AM

Ramon Smits said:

That is the same version that I'm using and that is also linked somewhere at the ndoc site.
# June 28, 2006 11:11 AM

Jan Schreuder on .Net said:

A&nbsp;few weeks back, I blogged about NDoc not being available for .Net 2.0. In that same blog post,...
# July 3, 2006 3:40 AM

Jan Schreuder on .Net said:

GhostDoc really helps you when documenting your code with XML tags! Find out why I use it and see if it's useful for yourselves.
# July 4, 2006 11:20 PM

Justin Crutchfield said:

NDoc is giving me problems.  I installed the GUI version from the link above.  It will build XML documentation, but it is not very readable.  I tried to generate the othe forms of documentation, but I got errors.  I was most interested in the Linear HTML.  Does anyone have any advice?

Justin

# January 14, 2009 2:00 PM

Jan Schreuder said:

Switch to SandCastle. Read my topics on this.

# January 14, 2009 5:40 PM

Arjan Douwes said:

NDoc had and my still even have the limitation that it requires an XML file to be generated by Visual Studio in order to generate the documentation file. This tend to be a problem with ASP.NET websites.

Alternatively you could take a look at Doxygen (www.doxygen.org) in combination with graphviz (www.graphviz.org). Both are open source tools.

With doxygen you can add additional information to your documentation such as a to do list, a test list, a bug list and additional documentation pages. It can even prepare the output so that it can be directly compiled into CHM file using the HTML Help WorkShop.

Graphviz is used to generate things like the call and caller graphs for a given method.

DoxyGen can be used for any C#.NET project as it scans the source files outside the IDE for XML documentation. Not sure how it performs on VB.NET project though.

Arjan

# January 22, 2009 4:57 PM
Leave a Comment

(required) 

(required) 

(optional)

(required) 


Please add 5 and 4 and type the answer here: