Fog Creek Software
Discussion Board




Welcome! and rules

Joel on Software

Looking for documentation examples

I need to document an existing .NET webservice for a vendor. Does anyone know of a utility that assists in doing this?

I'm thinking along the lines of something that lists the methods, fields & datatypes and leaves me to fill in high-level descriptions. This can be basic; UML diagrams would be overkill.

jfm424
Thursday, February 10, 2005

How about using .NET's inbuilt HTML Comments pages generator which works as follows:

Go right above your method and type in three forward slashes as such "///". .NET automatically takes the clue and generates the following template for you.

/// <summary>
///
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>

Now, the param names for my code were sender and e, but will be different for your webservice, however, the IDE will insert the appropriate names for you. All you have to do is modify the above template to something as follows:

/// <summary>
/// Describe your method's summary
/// </summary>
/// <param name="sender">Describe sender</param>
/// <param name="e">Describe e</param>

After doing this, go to Tools->Build Comment Web Pages...

You will see a static HTML page generated that neatly lays out what you have written above in a usable readable method.

This is based on the BIG assumption that you stated - you only need basic commenting such as what methods are used and what arguments are used.

For Web Serivces, you should ideally use a WSDL and a WSDL gives a clear picture of the exposed methods, args etc. But it looks like you're after something non-technical and readable.

Sheeshers
Thursday, February 10, 2005

I tried this and it didn't work. I use VB.NET and went to my code-behind file, tried this above a function and a sub, didn't do anything. You said HTML comments - should this be done in the HTML page? I don't put methods in the HTML page. Could you explain this a little more, it sounds intriguing.

SongSing Writer
Friday, February 11, 2005

These comments are called XML comments, and they are specific to the C# language. The Visual Studio HTML page generator (and the NDoc tool) only work with C# for this reason.

Chris Nahr
Friday, February 11, 2005

Even with C#, this is officially known to NOT work anymore. There is a workaround and an MSDN blogger has listed that in his post right here:

http://blogs.msdn.com/vseditor/archive/2004/07/16/185788.aspx

Sheeshers http://spaces.msn.com/members/ashishs
Friday, February 11, 2005

Addendum to previous post:

The issue mentioned arises with Windows XP Service Pack 2 only.

Sorry for the misleading post.

Sheeshers http://spaces.msn.com/members/ashishs
Friday, February 11, 2005

Also, this article only applies to Visual Studio's comment webpage feature which IMNSHO is crap anyway. If you want real documentation for your C# programs you should use NDoc.

Chris Nahr
Saturday, February 12, 2005

*  Recent Topics

*  Fog Creek Home