add documentation for generate_spirv_parser

diff --git a/docs/generate_spirv_parser.md b/docs/generate_spirv_parser.md
new file mode 100644 (file)
index 0000000..4d61318
--- /dev/null
+++ b/docs/generate_spirv_parser.md
@@ -0,0 +1,41 @@
+# generate_spirv_parser executable
+
+Parses the JSON in `khronos-spirv/*.grammar.json` and generates `spirv/spirv.h`, `spirv/spirv.cpp`, `spirv/parser.h`, and `spirv/parser.cpp`.
+
+## `generate_spirv_parser/ast.h`
+AST for the SPIR-V grammars.
+
+## `generate_spirv_parser/word_iterator.h`
+
+### `generate_spirv_parser::generate::Word_iterator`
+iterator that splits a string into words. Works for CamelCase word splitting as well.
+
+### `generate_spirv_parser::generate::Chained_word_iterator`
+iterator made from [chaining](https://docs.python.org/3/library/itertools.html#itertools.chain) several `Word_iterator`s together.
+
+### `generate_spirv_parser::generate::make_chained_word_iterator`
+helper function to construct `Chained_word_iterator`s.
+
+## `generate_spirv_parser/generate_spirv_parser.cpp`
+main driver code for `generate_spirv_parser`
+
+## `generate_spirv_parser/generate.h`
+
+### `generate_spirv_parser::generate::Generate_error`
+type for error from output code generation
+
+### `detail::keywords`
+list of C++ keywords and words that may become C++ keywords.
+
+### `detail::Generated_output_stream`
+A generated section of output code.
+Similar to a `std::ostringstream`.  
+Implements a custom indentation-control language. See [docs/generate_spirv_parser_indentation_control.md](generate_spirv_parser_indentation_control.md)  
+Members:
+- `Name_from_words_holder`: holds the result of a `name_from_words` call. Holds references to the arguments of the `name_from_words` call, so users should call `to_string` if they want to save the value for use outside the current expression.  
+Members:
+  - `to_string`: converts to a `std::string`.
+
+### `detail::name_from_words_*`
+splits all the inputs strings into words using `Chained_word_iterator`, then concatenates all the words together separated by underlines, finally applies the word capitalization modifications indicated by the function name. If the result is a C++ keyword (is found in `detail::keywords`), then append an additional underline.
+Returns a `Name_from_words_holder`.

diff --git a/docs/generate_spirv_parser_indentation_control.md b/docs/generate_spirv_parser_indentation_control.md
new file mode 100644 (file)
index 0000000..be93e7a
--- /dev/null
+++ b/docs/generate_spirv_parser_indentation_control.md
@@ -0,0 +1,21 @@
+# Documentation for the indentation-control language implemented by `generate_spirv_parser::generate::detail::Generated_output_stream`
+
+Indentation is controlled by several different values:
+- `start_indent_depth`: indentation depth that is changed to at the beginning of the next line.
+- `start_indent_depth_stack`: stack that is used to save and restore the value of `start_indent_depth`.
+- `indent_depth`: the indentation depth of the current line.
+- `output_indent_width`: the standard indentation step size, defaults to 4
+
+Each line is indented based on indentation change commands at the beginning of the line. After indenting the current line, but before interpreting the indentation change commands in the next line, `indent_depth` is set to the value of `start_indent_depth`.  
+Indentation commands:
+- <code style="white-space: pre">"    "</code> (4 spaces): Increase `indent_depth` by `output_indent_width`.
+- <code>"\`"</code> (single back-tick): Increase `indent_depth` by 1. Used for manual indentation.
+- `"@+"`: increase both `start_indent_depth` and `indent_depth` by `output_indent_width`.
+- `"@-"`: decrease both `start_indent_depth` and `indent_depth` by `output_indent_width`.
+- `"@_"`: decrease `start_indent_depth` by `output_indent_width`, while retaining `indent_depth` at it's current value.
+- `guard_macro`: write the name of the include-guard macro. The macro name is generated from the name of the file.
+- `literal("<text>")`: Write `<text>` without interpreting it as indentation-commands.
+- `push_start`: push the value of `start_indent_depth` onto `start_indent_depth_stack`.
+- `pop_start`: pop a value off of `start_indent_depth_stack` and write it into `start_indent_depth`.
+- `restart_indent`: sets `indent_depth` to the value of `start_indent_depth`.
+- `add_start_offset(offset)`: changes `start_indent_depth` by `offset`.