ASDoc fatal error

Question

I get an error while generating documentation for my Flex project (built with Flash Builder 4.6) using ASDoc:

[Fatal Error] toplevel.xml:3061:11: Element type "gmail.com" must be followed by either attribute specifications, ">" or "/>".
org.xml.sax.SAXParseException; systemId: path/to/toplevel.xml; lineNumber: 3061; columnNumber: 11; Element type "gmail.com" must be followed by either attribute specifications, ">" or "/>".
    at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
    at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
    at javax.xml.parsers.DocumentBuilder.parse(DocumentBuilder.java:205)
    at flex2.compiler.asdoc.AsDocHelper.createTopLevelClasses(AsDocHelper.java:66)
    at flex2.compiler.asdoc.AsDocAPI.createTopLevelClassesXML(AsDocAPI.java:401)
    at flex2.tools.ASDoc.asdoc(ASDoc.java:94)
    at flex2.tools.ASDoc.main(ASDoc.java:35)
Error: Could not create toplevel.xml: Element type "gmail.com" must be followed by either attribute specifications, ">" or "/>".

It seems that it's trying to use my e-mail address in the documentation, and that this is not working. I could not find anything related to this in the ASDoc templates directory and I don't know how ASDoc can know my e-mail address. By the way, the file toplevel.xml is not available for inspection after the error is thrown.

Answer 1

The error message given by the ASDoc generator is terribly misleading. What is happening is somewhere in your comments, you have an "illegal" character.

Since it's telling you the error message has to do with gmail.com, I'm guessing the illegal character is the at symbol (@). Since the ASDoc generator isn't telling you which line or even which class has the invalid character in it, you need to dig through every single class in your project until you find @gmail.com somewhere in the ASDoc comments.

After you have found it, replace the @ character with @, or remove the offending line entirely.

For more details, see StackOverflow: Include @ in ASDoc comments without any errors?