From 99b868c0f0ba0bd7a0d72c42becdd72c768d115a Mon Sep 17 00:00:00 2001
From: Christopher Willis-Ford <cwillisf@media.mit.edu>
Date: Mon, 2 Oct 2017 15:29:32 -0700
Subject: [PATCH] Explain when it's OK to omit <field> element

Also, alphabetize the `ArgumentType` and `BlockType` enums.
---
 src/engine/runtime.js                  | 7 +++++++
 src/extension-support/argument-type.js | 6 +++---
 src/extension-support/block-type.js    | 6 +++---
 3 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/src/engine/runtime.js b/src/engine/runtime.js
index d8a4ea998..1b3641ab7 100644
--- a/src/engine/runtime.js
+++ b/src/engine/runtime.js
@@ -459,10 +459,17 @@ class Runtime extends EventEmitter {
             const argInfo = blockInfo.arguments[placeholder] || {};
             const argTypeInfo = ArgumentTypeMap[argInfo.type] || {};
             const defaultValue = (typeof argInfo.defaultValue === 'undefined' ? '' : argInfo.defaultValue.toString());
+
+            // <value> is the ScratchBlocks name for a block input.
+            // The <shadow> is a placeholder for a reporter and is visible when there's no reporter in this input.
             inputList.push(`<value name="${placeholder}"><shadow type="${argTypeInfo.shadowType}">`);
+
+            // <field> is a text field that the user can type into. Some shadows, like the color picker, don't allow
+            // text input and therefore don't need a field element.
             if (argTypeInfo.fieldType) {
                 inputList.push(`<field name="${argTypeInfo.fieldType}">${defaultValue}</field>`);
             }
+
             inputList.push('</shadow></value>');
 
             return `%${argNum}`;
diff --git a/src/extension-support/argument-type.js b/src/extension-support/argument-type.js
index 3f2aa9255..70381c84b 100644
--- a/src/extension-support/argument-type.js
+++ b/src/extension-support/argument-type.js
@@ -1,8 +1,8 @@
 const ArgumentType = {
-    NUMBER: 'number',
-    STRING: 'string',
     BOOLEAN: 'Boolean',
-    COLOR: 'color'
+    COLOR: 'color',
+    NUMBER: 'number',
+    STRING: 'string'
 };
 
 module.exports = ArgumentType;
diff --git a/src/extension-support/block-type.js b/src/extension-support/block-type.js
index 663e2e3e3..587f7d598 100644
--- a/src/extension-support/block-type.js
+++ b/src/extension-support/block-type.js
@@ -1,9 +1,9 @@
 const BlockType = {
-    COMMAND: 'command',
-    REPORTER: 'reporter',
     BOOLEAN: 'Boolean',
+    COMMAND: 'command',
+    CONDITIONAL: 'conditional',
     HAT: 'hat',
-    CONDITIONAL: 'conditional'
+    REPORTER: 'reporter'
 };
 
 module.exports = BlockType;