From 53424699e44d70c92f8494b4238ddabb6302d680 Mon Sep 17 00:00:00 2001
From: Max Brunsfeld <maxbrunsfeld@gmail.com>
Date: Fri, 20 Nov 2015 21:39:15 -0800
Subject: [PATCH] Comment all the steps of prepare_grammar

---
 .../prepare_grammar/prepare_grammar.cc        | 31 ++++++++++++++-----
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/src/compiler/prepare_grammar/prepare_grammar.cc b/src/compiler/prepare_grammar/prepare_grammar.cc
index f8ff3a59..6731b015 100644
--- a/src/compiler/prepare_grammar/prepare_grammar.cc
+++ b/src/compiler/prepare_grammar/prepare_grammar.cc
@@ -18,30 +18,47 @@ using std::make_tuple;
 
 tuple<SyntaxGrammar, LexicalGrammar, const GrammarError *> prepare_grammar(
   const Grammar &input_grammar) {
-  // Convert all string-based `NamedSymbols` into numerical `Symbols`
+  /*
+   * Convert all string-based `NamedSymbols` into numerical `Symbols`
+   */
   auto intern_result = intern_symbols(input_grammar);
   const GrammarError *error = intern_result.second;
   if (error)
     return make_tuple(SyntaxGrammar(), LexicalGrammar(), error);
 
-  // Separate grammar into lexical and syntactic components
+  /*
+   * Separate grammar into lexical and syntactic components
+   */
   auto extract_result = extract_tokens(intern_result.first);
   error = get<2>(extract_result);
   if (error)
     return make_tuple(SyntaxGrammar(), LexicalGrammar(), error);
 
-  // Replace `Repeat` rules with pairs of recursive rules
-  InitialSyntaxGrammar syntax_grammar = expand_repeats(get<0>(extract_result));
+  /*
+   * Replace `Repeat` rules with pairs of recursive rules
+   */
+  InitialSyntaxGrammar syntax_grammar1 = expand_repeats(get<0>(extract_result));
 
-  // Expand `String` and `Pattern` rules into full rule trees
+  /*
+   * Expand `String` and `Pattern` rules into full rule trees
+   */
   auto expand_tokens_result = expand_tokens(get<1>(extract_result));
   LexicalGrammar lex_grammar = expand_tokens_result.first;
   error = expand_tokens_result.second;
   if (error)
     return make_tuple(SyntaxGrammar(), LexicalGrammar(), error);
 
-  return make_tuple(flatten_grammar(syntax_grammar),
-                    normalize_rules(lex_grammar), nullptr);
+  /*
+   * Flatten syntax rules into lists of productions.
+   */
+  SyntaxGrammar syntax_grammar = flatten_grammar(syntax_grammar1);
+
+  /*
+   * Ensure all lexical rules are in a consistent format.
+   */
+  lex_grammar = normalize_rules(lex_grammar);
+
+  return make_tuple(syntax_grammar, lex_grammar, nullptr);
 }
 
 }  // namespace prepare_grammar