We all understand the need to comprehensively document our class libraries and to keep it up to date with the code base. And still, documentation is an ongoing pain for all of us. The Visual Studio .NET IDE takes a first big step in easing that pain. It allows to document your code in a way that the compiler can create an XML document describing your classes, methods, properties, etc. This article explains how to use this feature and then create a basic help file out of it.
Automate the process of documenting your code
About The Author
Eugenia Loli
Ex-programmer, ex-editor in chief at OSNews.com, now a visual artist/filmmaker.
Follow me on Twitter @EugeniaLoli
javac has been doing this since a long time, and there are a few utilities out there to enhance javac output.
I don’t understand why it’s hard for MS to innovate. For a company of its size, too many of its products and features are direct rip offs.
IMHO code should be documented first, then written. In the real world, anyway.
Anything else is just an afterthought. Take doxygen output for example.
so, micros~1 copies javadoc:
http://java.sun.com/j2se/javadoc/
…and it’s news?
I wonder why! come on guys! I dont believe that MS believes either that this is innovation, probably the writer of the news post had not heard of javadoc and related concepts!
Regards
The concept of inline documentation is not new
I think he meant new in .NET, not new as in never been done before. Anyway, I’m not here to defend either .NET or Java, as I consider them to be both equally horrible.
ndoc (http://ndoc.sourceforge.net) is a great document generator for .NET projects. Much easier than generating documentation by hand!
I found the XML-based doc comments much, much better than JavaDoc, but I’m a huge XML fan. This support for this documentation was also awesome in VisualStudio.NET… you start a doc comment and it automagically fills in all the method types and arguments for you to document. Very nice.
– chrish
It’s been done in an easier to use way by Doxygen (which supports XML, HTML, CHM, Latex and Manpage outputs).
The great advantage of Doxygen is that it supports, C, C++, Java, PHP (just about) and Pascal (with help from pas2dox). This makes it a great all-round tool for commenting source.
This is not to say that commenting source is enough. Ideally you should comment every function and class to explain what it does, and then write the implementation in such as way that it can be easily comprehended, hence literate programming.
However the advantage of Doxygen, Javadoc and other coding systems is not that it describes to a user what a function does, but that is describes how the functions and classes all fit together to form an application. This requires a certain amount of forethought on the programmers part (and a few @see and @page commands).
For anyone who doubts this, try using Doxygen with the Graphviz “dot” tool. Assuming you choose to document everything, it will create not only an inheritance diagram, but a “clickable” collaboration diagram as well illustrating the links between the current class and all other classes. That’s fantastic.
nDoc is a must for .NET developers.
It produce a high quality documentation and can be easily incorporated in a daily build process.
You should not use VS2003 to generate documentation to give to other developers since not all information is included.
Having a tool to go through your tags to generate documentation is certainly nothing new. Javadoc has been doing it for years. Having your IDE do all the assmonkeying so you don’t have to, however, is.
I like Java and all, but having used javadoc, I have to say that it made me want to repeatedly stab McNealy’s face.
It doesn’t have anything to do with zealotry, in my opinion. I program in C# every day at work, so I don’t have anything against it simply because it is a Microsoft technology. I actually like the language quite well.
However, I would have to agree with all those you are calling zealots. Microsoft’s implementation of automatically documenting your code is quite similar to Java’s and nowhere near as good as other tools. It is nothing innovative or amazing. It is a second class citizen in the technological caste system; nothing to really get excited about.
Again, it isn’t about zealotry, it’s simply about facts.
Its not even new to .NET really.
Yeah, there is nothing new here and I’m surprised that it’s even a story, but it is funny to watch paranoid java developers with inferiority complexes.
http://www.doxygen.org Is a great tool and covers several languages.
I also swear by doxygen. It is by far the best code documentation tool I have yet encountered. I use it with C, C++ and Java every day. I love the dependency graphs and collaboration diagrams. You have to pay big money to get that functionality from specialized tools.
I moved a framework from Java to C#. The VS.NET tool is unable to manage correctly external documentation. The developpers of this tool really made the minimum to help creation of inline doc for attributes/methods/properties.
Luckily, I found NDoc to help me in my task and have been able to match the same level as with javadoc but with the look and feel of MSDN.
At the end of this painful process, we are in the evaluation of doxygen in order to auto-document the framework. Autodoc tool of VS.NET/.NET is simply unmature (but still have its use inside VS.NET space).
Is it possible to use doxygen inside Vs.net, with VB.Net?
Additionally, is there any free/cheap tool that generates class diagrams (with dependencies and interfaces) from the source code?
It’s been mentioned before, and it’s worth mentioning again: NDoc is an essential tool in any .Net developers toolbox. It’s capabilities go well beyond what’s built into VS.NET.
It’s also worth mentioning that the “Build Comment Web Pages” feature is being dropped in Whidbey (VS 2005): http://weblogs.asp.net/ericgu/archive/2004/06/25/166046.aspx , it won’t really be missed though.
I don’t ever understand that always when MS comes up with a staggering new “idea” that has been implemented elsewhere for ages, it always gets in the news and (l)users come to praise it. They just don’t care about anything else than waiting for MS to release “their” new ideas and stuff (think DB-based FS, popup blocking, os-level firewall, etc.)
Doxygen & javadoc for the masses.
MS has always been big on making a good IDE. Utility tools to generate documentation from your code is no big thing. When you compare what IDEA does, it makes Javadoc look silly. IDEA Writes the method comments and updates the method comments every time you change the method signature. That’s what an IDE SHOULD do. I’ve seen many projects start off trying to develop their code with comments, but they inevitibly slack off, especially when they realize that the comments they wrote a month ago describe features of the class/method that have been refactored out of the class/method, but the method comment hasn’t changed. If your IDE is generating (at least the skeleton) of the method comment, at least it’s keeping the signature of the method up to date, which is something that a documentation tool like javadoc cannot do. What could be better than having something take the tedium out of code commenting?
If you’ve ever read Fowler’s _Refactoring_ you’ll know what I’m about to say: if your code needs comments, you have a problem. Your code should be easy to interpret. Use verbose, descriptive method names, and use less logic spread around more functions. This is really the only self-maintaining method of documentation: descriptive method names and easy to follow code. Leave the comments to describe basic, invariant intentions about your program. If possible, use a UML class-diagram generating tool, and run it with your normal build to keep the picture of the class structure in sync with the code.
If you’ve ever read Fowler’s _Refactoring_ you’ll know what I’m about to say: if your code needs comments, you have a problem.
I think the idea of fully self-documenting code was proven unfeasible by COBOL.
Surely easy to comprehend code without comments is better than hard to comprehend code with comments, but at the same time having a description of high level interactions of code in comments is certainly much better than leaving the reader to figure that out for themselves.