Remove debug/error language from $comment

[jdesrosiers]

Resolves #1628

I rewrote how $comment is defined. I think it's inline with what it was before, but it removes some language that doesn't make sense to me.

• I removed the debugger/error language because I don't understand what that means and no one could explain it to me.
• I clarified that it can be used for developer tooling directives.
• I removed the part about stripping $comment during processing. That's an implementation detail that I think follows clearly from saying it MUST NOT affect validation and annotation and doesn't need to be said explicitly.