ASDoc comments should be ignored (as if they were regular comments) when they appear in unexpected places

[joshtynjala]

Example:

package
{
	public class CommentInsideFunctionParameters
	{
		public function CommentInsideFunctionParameters(param:Object=null /** asdoc comment is bad? **/)
		{
		}
	}
}

The Royale compiler gives the following error, but the Flex SDK compiler treated it as a normal comment:

')' is not allowed here

But this code gives no errors:

package
{
	public class CommentInsideFunctionParameters
	{
		public function CommentInsideFunctionParameters(param:Object=null /* regular comment is okay! */)
		{
		}
	}
}

RawASTokenizer.lex creates a TOKEN_ASDOC_COMMENT for asdic comments, but it doesn't create a token for regular comments (unless a particular flag is enabled). ASParser.g can handle this token in a few places, but if it encounters the token somewhere it doesn't expect, it results in the error above.

In the case above, formalParameters or formal in ASParser.g is where the ASDoc comment is unexpected, and that might be easy enough to work around, but there are many other places where you could try to add an ASDoc comment, and it would also result in errors.

A real fix may involve adding a new flag to ignore ASDoc comments (in the same way that regular comments are ignored or parsed), except when they are actually needed.

[greg-dove]

I think this is related: I have seen similar issues with ASDoc comments before an else statement
It will give a Syntax Error saying expected SCOPE_CLOSE but got 'else' (or similar). Swapping to normal comment, as described above for parameters, fixes it.