Include @ in ASDoc comments without any errors?

Question

If you have the @ symbol in your ASDoc, the code will compile, but the generator for the ASDoc will yell out an unintelligible error message.

/**
 * Removes the following characters which are forbidden:
 *    @/\"#$%&'()*:;<=>!?
 */
public function removeForbiddenChars(str:String):String

Is there any way to include the @ symbol in your ASDoc without an error being thrown?

Answer 1

According to documentation by Adobe:

ASDoc passes all HTML tags and tag entities in a comment to the output. Therefore, if you want to use special characters in a comment, enter them using HTML code equivalents. For example, to use a less-than (<) or greater-than (>) symbols in a comment, use < and >. To use the at-sign (@) in a comment, use @. Otherwise, these characters are interpreted as literal HTML characters in the output.

Although not mentioned in the documentation,a fourth symbol that is not allowed is &, and must be replaced by &.

So, if one were to follow these instructions for the example ASDoc:

/**
 * Removes the following characters which are forbidden:
 *    @/\"#$%&'()*:;<=>!?
 */
public function removeForbiddenChars(str:String):String

It may not be clear when looking at the comment in your editor, but it will be clear once the ASDoc has been compiled into HTML. Perhaps one could phrase the comment in such a way that the special characters aren't used:

Removes /\"#$%'()*:;=!? as well as the 'at' symbol (@), the ampersand symbol (&), the 'less than' symbol (<), and the 'greater than' symbol (<)