I was just looking at some C# code at work today and it had XML Documentation (like javadoc or python docstrings, only with XML). Who was the idiot that came up with that idea? It's the most insane thing I've ever seen. Let's look at the predecessors to C#'s XML documentation:
Javadoc:
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
Then, doxygen, which looks a lot like javadoc:
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
Unfortunately Genshi doesn't syntax highlight the javadoc comments. But it looks fairly readable. Let's try a python docstring example. There is no one standard. One of the documentation generators for Python, Epydoc understands plaintext, javadoc, epydoc, and reStructuredText.
Python code with epydoc style docstrings:
def x_intercept(m, b):
"""
Return the x intercept of the line M{y=m*x+b}. The X{x intercept}
of a line is the point at which it crosses the x axis (M{y=0}).
This function can be used in conjuction with L{z_transform} to
find an arbitrary function's zeros.
@type m: number
@param m: The slope of the line.
@type b: number
@param b: The y intercept of the line. The X{y intercept} of a
line is the point at which it crosses the y axis (M{x=0}).
@rtype: number
@return: the x intercept of the line M{y=m*x+b}.
"""
return -b/m
Python code with one example of reStructuredText docstrings (this one includes the types of the parameters but they aren't necessary):
def fox_speed(size, weight, age):
"""
Return the maximum speed for a fox.
:Parameters:
size
The size of the fox (in meters)
weight : float
The weight of the fox (in stones)
age : int
The age of the fox (in years)
"""
#[...]
I couldn't find any nice examples for C# XML Documentation. The C# XML Documentation Tutorial has some examples, but conveniently, none that include all the tags that I would need to replicate the javadoc example I showed above. So I'll convert the Java example to C#:
/// <summary>
/// Returns an Image object that can then be painted on the screen.
/// The url argument must specify an absolute {@link URL}. The name
/// argument is a specifier that is relative to the url argument.
///
/// This method always returns immediately, whether or not the
/// image exists. When this applet attempts to draw the image on
/// the screen, the data will be loaded. The graphics primitives
/// that draw the image will incrementally paint on the screen.</summary>
///
/// <param name="url">an absolute URL giving the base location of the image</param>
/// <param name="name">the location of the image, relative to the url argument</param>
/// <returns>
/// the image at the specified URL</returns>
/// <seealso cref="Image">
/// Read more about the Image class</seealso>
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
I followed Microsoft's convention (because they know best) of putting the opening tags on a line on their own.
The javadoc sucks because you have to put a <p> (or <br />?) to make a new line which is stupid. Otherwise it's pretty readable, and same goes for doxygen. Especially the @param and @return tags. The Epydoc-style python docstrings suck. You have to specify the type using a @type tag and the return type using an @rtype tag. The reStructuredText example looks the best to me. No tags at all, except for the :Parameters: heading which should be there anyways. The C# comments are an eyesore. Even if Visual Studio had syntax highlighting for the comments it would suck. Did Microsoft look at the two major previous implementations (doxygen and javadoc) and decide that XML was a better way to document code?
I recently saw an interesting comment in scipy's source about one of scipy's guiding principles in designing the docstring standard for their codebase:
A guiding principle is that human readers of the text are given precedence over contorting docstrings so our tools produce nice output. Rather than sacrificing the readability of the docstrings, we have written pre-processors to assist tools like epydoc_ and sphinx_ in their task.
Microsoft clearly took the opposite route and decided to make code documentation readability by human readers a low priority.
Recent comments