make 'names' accept only an array of strings, add warning comments about where new functions should be added

CONTRIBUTING.md

@@ -42,14 +42,18 @@ If you do, check out [extract_ttfs.py](metrics/extract_ttfs.py).
 
 #### Adding new functions
 
-Most functions are handled in the [functions.js](src/functions.js) file. Read
-the comments in there to get started. If the function you want to add has
-similar output to an existing function, see if you can add a new line to that
-file to get it to work.
+New functions should be added in [src/functions](src/functions) using
+`defineFunction` from [defineFunction.js](src/defineFunction.js).  Read the
+comments in this file to get started.  Look at
+[phantom.js](src/functions/phantom.js) and
+[delimsizing.js](src/functions/delimsizing.js) as examples of how to use
+`defineFunction`.  Notice how delimsizing.js groups several related functions
+together in a single call to `defineFunction`.
 
-If your function isn't similar to an existing function, you'll need to add a
-line to `functions.js` as well as adding an output function in
-[buildHTML.js](src/buildHTML.js) and [buildMathML.js](src/buildMathML.js).
+The new method of defining functions combines methods that were previously
+spread out over three different files [functions.js](src/functions.js),
+[buildHTML.js](src/buildHTML.js), [buildMathML.js](src/buildMathML.js) into a
+single file.  The goal is to have all functions use this new system.
 
 ## Testing
 

src/buildHTML.js

@@ -1,5 +1,6 @@
-/* eslint no-console:0 */
 /**
+ * WARNING: New methods on groupTypes should be added to src/functions.
+ *
  * This file does the main work of building a domTree structure from a parse
  * tree. The entry point is the `buildHTML` function, which takes a parse tree.
  * Then, the buildExpression, buildGroup, and various groupTypes functions are

src/buildMathML.js

@@ -1,4 +1,6 @@
 /**
+ * WARNING: New methods on groupTypes should be added to src/functions.
+ *
  * This file converts a parse tree into a cooresponding MathML tree. The main
  * entry point is the `buildMathML` function, which takes a parse tree from the
  * parser.

src/defineFunction.js

@@ -12,7 +12,7 @@ type FunctionSpec<T> = {
 
     // The first argument to defineFunction is a single name or a list of names.
     // All functions named in such a list will share a single implementation.
-    names: string | Array<string>,
+    names: Array<string>,
 
     // Properties that control how the functions are parsed.
     props: {
@@ -107,12 +107,6 @@ export default function defineFunction({
     htmlBuilder,
     mathmlBuilder,
 }: FunctionSpec<*>) {
-    if (typeof names === "string") {
-        names = [names];
-    }
-    if (typeof props === "number") {
-        props = { numArgs: props };
-    }
     // Set default values of functions
     const data = {
         numArgs: props.numArgs,

src/functions.js

@@ -3,9 +3,17 @@ import ParseError from "./ParseError";
 import ParseNode from "./ParseNode";
 import {default as _defineFunction, ordargument} from "./defineFunction";
 
+// WARNING: New functions should be added to src/functions.
+
 // Define a convenience function that mimcs the old semantics of defineFunction
 // to support existing code so that we can migrate it a little bit at a time.
 const defineFunction = function(names, props, handler) {
+    if (typeof names === "string") {
+        names = [names];
+    }
+    if (typeof props === "number") {
+        props = { numArgs: props };
+    }
     _defineFunction({names, props, handler});
 };
 

src/functions/delimsizing.js

@@ -231,7 +231,7 @@ defineFunction({
 
 defineFunction({
     type: "middle",
-    names: "\\middle",
+    names: ["\\middle"],
     props: {
         numArgs: 1,
     },

src/functions/phantom.js

@@ -8,7 +8,7 @@ import * as mml from "../buildMathML";
 
 defineFunction({
     type: "phantom",
-    names: "\\phantom",
+    names: ["\\phantom"],
     props: {
         numArgs: 1,
     },
@@ -38,7 +38,7 @@ defineFunction({
 
 defineFunction({
     type: "hphantom",
-    names: "\\hphantom",
+    names: ["\\hphantom"],
     props: {
         numArgs: 1,
     },
@@ -79,7 +79,7 @@ defineFunction({
 
 defineFunction({
     type: "vphantom",
-    names: "\\vphantom",
+    names: ["\\vphantom"],
     props: {
         numArgs: 1,
     },