Add grammar docstrings to QASM3 parser (#2222)

This PR:
 1. Fixes a bug with block statements
 2. Adds grammar docstrings to the QASM3 parser.
3. Adds the invalid tests in the reference parser to make sure they are
invalid for our parser as well.

Author: orpuente-MS

compiler/qsc_qasm3/src/parser/expr.rs

@@ -680,6 +680,7 @@ fn unescape(s: &str) -> std::result::Result<String, usize> {
     Ok(buf)
 }
 
+/// Grammar: `LBRACKET expression RBRACKET`.
 pub(super) fn designator(s: &mut ParserContext) -> Result<Expr> {
     token(s, TokenKind::Open(Delim::Bracket))?;
     let expr = expr(s)?;
@@ -756,6 +757,7 @@ fn hardware_qubit(s: &mut ParserContext) -> Result<HardwareQubit> {
     })
 }
 
+/// Grammar: `Identifier indexOperator*`.
 pub(crate) fn indexed_identifier(s: &mut ParserContext) -> Result<IndexedIdent> {
     let lo = s.peek().span.lo;
     let name: Ident = ident(s)?;
@@ -768,6 +770,15 @@ pub(crate) fn indexed_identifier(s: &mut ParserContext) -> Result<IndexedIdent>
     })
 }
 
+/// Grammar:
+/// ```g4
+/// LBRACKET
+/// (
+///     setExpression
+///     | (expression | rangeExpression) (COMMA (expression | rangeExpression))* COMMA?
+/// )
+/// RBRACKET
+/// ```
 fn index_operand(s: &mut ParserContext) -> Result<IndexElement> {
     token(s, TokenKind::Open(Delim::Bracket))?;
     let index = index_element(s)?;

compiler/qsc_qasm3/src/parser/prgm.rs

@@ -13,6 +13,7 @@ use crate::{
 
 use super::ParserContext;
 
+/// Grammar: `version? statementOrScope* EOF`.
 pub(super) fn parse(s: &mut ParserContext) -> Result<Program> {
     let lo = s.peek().span.lo;
     let version = opt(s, parse_version)?;
@@ -29,6 +30,7 @@ pub(super) fn parse(s: &mut ParserContext) -> Result<Program> {
     })
 }
 
+/// Grammar: `OPENQASM VersionSpecifier SEMICOLON`.
 fn parse_version(s: &mut ParserContext<'_>) -> Result<Version> {
     s.expect(WordKinds::OpenQASM);
     token(s, TokenKind::Keyword(crate::keyword::Keyword::OpenQASM))?;