Flash CS3 Documentation

Learning ActionScript 2.0 in Adobe Flash > Classes > Example: Writing custom classes > Documenting the classes

Documenting the classes

Using comments in your classes and interfaces is an important part of documenting them for other users. For example, you might want to distribute your class files into the Flash community, or you might be working with a team of designers or developers who will use your class files in their work or as part of a project you're working on. Documentation helps other users understand the purpose and origins of the class.

There are two kinds of comments in a typical class or interface file: documentation comments and implementation comments. You use documentation comments to describe the code's specifications, but not the implementation. You use implementation comments to comment out code or to comment on the implementation of particular sections of code. The two kinds of comments use slightly different delimiters. Documentation comments are delimited with /** and */, and implementation comments are delimited with /* and */.

Use documentation comments to describe interfaces, classes, methods, and constructors. Include one documentation comment per class, interface, or member, and place it directly before the declaration.

If you have to document additional information that does not fit into the documentation comments, use implementation comments (in the format of block comments or single-line comments, as described in About comments). Implementation comments, if you add them, directly follow the declaration.

To document your class files:

1. Open ClassA.as and ClassB.as in the Flash authoring tool.
2. Modify the ClassA class file and add the new code to the top of the class file (the changes to make appear in boldface):

   /**
       ClassA class
       version 1.1
       6/21/2005
       copyright Adobe Systems Incorporated
    */
   class com.adobe.utils.ClassA {
       private static var _className:String = "ClassA";
   
       public function ClassA() {
           trace("ClassA constructor");
       }
       public function doSomething():Void {
           trace("ClassA - doSomething()");
       }
   }
   

   The code above added a comment to the top of the class file. It's always a good idea to add comments to your ActionScript and Flash files so that you can add useful information such as the author of the class, date last modified, copyright information, or any potential issues/bugs that may be present in the file.

3. Add a similar comment to the top of the ClassB.as ActionScript file, changing the class name and any other information as you see fit.
4. Save both ActionScript files before you proceed.

You might also add the block, single-line, or trailing comments within the class's code. For information on writing good comments within your code, see Writing good comments. For general information about comments, see Single-line comments, Multiline comments, and Trailing comments.

To learn how to use these custom class files in a SWF file, see Example: Using custom class files in Flash.

Flash CS3