ASDoc tags

Copies an ASDoc comment from the referenced location. The main description, @param, and @return content is copied; other tags are not copied.

You typically use the @copy tag to copy information from a source class or interface not in the inheritance list of the destination class. If the source class or interface is in the inheritance list, use the @inheritDoc tag instead.

You can add content to the ASDoc comment before the @copy tag.

Specify the location by using the same syntax as you do for the @see tag. For more information, see Using the @see tag.

@copy #stop

@copy flash.display.MovieClip#stop()

Specifies the default value for a property, style, or effect. The ASDoc tool automatically creates a sentence in the following form when it encounters an @default tag:

The default value is value. 

Use the first form in a comment for an [Event] metadata tag. It specifies the constant that defines the value of the Event.type property of the event object associated with the event. The ASDoc tool copies the description of the event constant to the referencing class.

Use the second form in the comment for the constant definition. It specifies the name of the event associated with the constant. If the tag is omitted, ASDoc cannot copy the constant's comment to a referencing class.

See Documenting effects, events, and styles

Defines a code example in an ASDoc comment. By preceding the code example with this tag, ASDoc applies style properties, generates a heading, and puts the code example in the correct location.

Enclose the code in <listing version="3.0"></listing> tags.

Whitespace formatting is preserved and the code is displayed in a gray, horizontally scrolling box.

If the code inside the <listing> tags uses literal “<“, “>”, or”&” characters, convert them to the HTML character-code equivalent.

@example The following code sets the volume level for your sound:

<listing version="3.0">

var mySound:Sound = new Sound(); mySound.setVolume(VOL_HIGH);

</listing>

Use this tag in an ASDoc comment in an external example file that is referenced by the @includeExample tag. The ASDoc comment must precede the first line of the example, or follow the last line of the example.

External example files support one comment before and one comment after example code.

/**

* This text does not appear

* in the output.

* @exampleText But this does.

*/

@includeExample textFile

Imports an example text file into the ASDoc output. ASDoc searches for the example file based on the package name of the class and the directory specified by the -examples-path option to the ASDoc tool.

For example, you use the examples-path option to set the directory to c:\examples. To add an example for the mx.controls.Button class, place it in the mx\controls\directory under c:\examples, meaning the c:\examples\mx\controls directory.

@includeExample buttonExample/ButtonExample.mxml

ASDoc looks for an example in the directory c:\examples\mx\controls\buttonExample.

If you insert this tag in the comment for a class, the example appears at the end of the output HTML file. If you insert it in the ASDoc comment for a class element, the example appears in the detailed description of the element.

@includeExample ButtonExample.mxml

Copies the comment from the superclass into the subclass, or from an interface implemented by the subclass. Use this tag in the comment of an overridden method or property. You cannot use this tag with comments on metadata tags.

The main ASDoc comment, @param, and @return content are copied; other tags are not. You can add content to the comment before the @inheritDoc tag.

When you include this tag, ASDoc uses the following search order:

1. Interfaces implemented by the current class, in alphabetical order of the package and class name, and all their base-interfaces.

2. Immediate superclass of current class.

3. Interfaces of immediate superclass and all their base-interfaces.

4. Repeat steps 2 and 3 until the Object class is reached.

You can also use the @copy tag, but the @copy tag is for copying information from a source class or interface that is not in the inheritance chain of the subclass.

Hides the text attached to the tag in the generated output. The hidden text can be used for internal comments.

Adds a descriptive comment to a method parameter. The paramName argument must match a parameter definition in the method signature.

Exclude the element from the generated output.

To omit an entire class, put the @private tag in the ASDoc comment for the class; to omit a single class element, put the @private tag in the ASDoc comment for the element.

Adds a Returns section to a method description with the specified text. ASDoc automatically determines the data type of the return value.

Adds a See Also heading with a link to a class element. For more information, see Using the @see tag.

Do not include HTML formatting characters in the arguments to the @see tag.

@since text

Adds a Since section to a class or element.

@since January 12, 2009

Documents an error that a method can throw.