From 381fcc321510a675cc63370d0db331dccf3201e7 Mon Sep 17 00:00:00 2001
From: Carl Beekhuizen <carl.beek@gmail.com>
Date: Mon, 3 Jun 2019 15:14:20 +0200
Subject: [PATCH] Adds label explainer

---
 scripts/README.md     | 32 ++++++++++++++++++++++++++++++++
 scripts/build_spec.py |  8 ++++----
 2 files changed, 36 insertions(+), 4 deletions(-)
 create mode 100644 scripts/README.md

diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 000000000..d6ce4c1bd
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,32 @@
+# Building pyspecs from specs.md
+
+The benefits of the particular spec design is that a given `spec.md` file can be converted to a `spec.py` file for the purposes of testing and linting. The result of this is that bugs are discovered and patched more quickly.
+
+Specs can bue built from either a single markdown document or multiple files that must be combined in a given order. Given 2 spec objects, `build_spec.combine_spec_objects` will combine them into a single spec object which, subsequently, can be converted into a `specs.py`.
+
+## Usage
+
+For usage of the spec builder run `python3 -m build_spec --help`.
+
+## `@Labels` and inserts
+
+The functioning of the spec combiner is largely automatic in that given `spec0.md` and `spec1.md`, in that SSZ Objects will be extended and old functions will be overwritten. Extra functionality is provided for more granular control over how files are combined. In the event that only a small portion of code is to be added to an existing function, insert functionality is provided. This saves having to completely redefine the old function from `spec0.md` in `spec1.md`. This is done by marking where the change is to occur in the old file and marking which code is to be inserted in the new file. This is done as follows:
+
+* In the old file, a label is added as a python comment marking where the code is to be inserted. This would appear as follows in `spec0.md`:
+
+```python
+def foo(x):
+    x << 1
+    # @YourLabelHere
+    return x
+```
+
+* In spec1, the new code could then be inserted by having a code-block that looked as follows:
+
+```python
+#begin insert @YourLabelHere
+    x += x
+#end insert @YourLabelHere
+```
+
+**Note** that the code to be inserted has the **same level of indentation** as the surrounding code of its destination insert point.
diff --git a/scripts/build_spec.py b/scripts/build_spec.py
index 2266af4ef..4ba9b616a 100644
--- a/scripts/build_spec.py
+++ b/scripts/build_spec.py
@@ -154,10 +154,10 @@ def objects_to_spec(functions: Dict[str, str],
     return spec
 
 
-def combine_functions(old_funcitons: Dict[str, str], new_functions: Dict[str, str]) -> Dict[str, str]:
+def combine_functions(old_functions: Dict[str, str], new_functions: Dict[str, str]) -> Dict[str, str]:
     for key, value in new_functions.items():
-        old_funcitons[key] = value
-    return old_funcitons
+        old_functions[key] = value
+    return old_functions
 
 
 def combine_constants(old_constants: Dict[str, str], new_constants: Dict[str, str]) -> Dict[str, str]:
@@ -184,7 +184,7 @@ def dependency_order_ssz_objects(objects: Dict[str, str]) -> Dict[str, str]:
 
 def combine_ssz_objects(old_objects: Dict[str, str], new_objects: Dict[str, str]) -> Dict[str, str]:
     """
-    Thakes in old spec and new spec ssz objects, combines them,
+    Takes in old spec and new spec ssz objects, combines them,
     and returns the newer versions of the objects in dependency order.
     """
     for key, value in new_objects.items():