I’m currently documenting all classes of the as2lib. Good documentation is often neglected in the world of ActionScript. Although it is very important. Thus here a few guidelines.
Why should I document code?
It’s quite easy to answer this question. Others too wanna know what’s going on or how they can use the code. And that without rummaging through all the stuff. But it’s also a help for you. Imagine you write a piece of code and years later you need to use it. You probably don’t know anymore how to work with it. And without good documentation you had to spend maybe an hour to just get the whole thing to work.
How do I document?
There exist a few standards. These standards are actually from a Java background but you can use them in every language. It’s important to pay attention which standards you documentation tool uses to extract the documentation properly.
The follwing link may be useful: http://java.sun.com/j2se/javadoc/writingdoccomments/.
Let’s start:
The Basic Construct:
/**
*
*/
That’s the basic construct. You probably know it. Just use it for every doc comment.
Block Tags:
Block tags are tags preceded by an @. The one you do probably need at most are: @param, @return, @see, @throws, @author and @version. There do exist more. You can find them with a big description under the link I posted above.
How a Doc Comment is Made Up:
/**
* [description]
*
* [block tags]
*/
Example:
I’ll just use the example from the above link because it is (almost) perfect:
-
/**
-
* 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.
-
*
-
* @param url an absolute URL giving the base location of the image
-
* 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;
-
}
-
}
I’m sorry for the bad design (no spaces etc.) but MovableType screws the whole thing up. If you know how to fix it let me know.
[Edit]The spaces work now. At least in the example.[/Edit]
