From 99b2afa935410c1e6c5d82617b89fcc3a74d481e Mon Sep 17 00:00:00 2001
From: Ashish Myles <marcianx@gmail.com>
Date: Fri, 18 May 2018 20:27:52 -0400
Subject: [PATCH] Specify flow output types for htmlBuilder and mathmlBuilder.
 (#1324)

* Specify flow output types for htmlBuilder and mathmlBuilder.

* Add TODOs to refactor to improve the return type of mathmlBuilder.
---
 src/defineEnvironment.js |  8 ++++----
 src/defineFunction.js    | 17 +++++++++++------
 src/functions/op.js      |  4 ++++
 src/mathMLTree.js        |  4 ++--
 4 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/src/defineEnvironment.js b/src/defineEnvironment.js
index 540afb26..1f3e29e4 100644
--- a/src/defineEnvironment.js
+++ b/src/defineEnvironment.js
@@ -7,7 +7,9 @@ import ParseNode from "./ParseNode";
 
 import type Parser from "./Parser";
 import type {ArgType, Mode} from "./types";
+import type {HtmlDomNode} from "./domTree";
 import type {NodeType} from "./ParseNode";
+import type {MathNode} from "./mathMLTree";
 
 /**
  * The context contains the following properties:
@@ -84,13 +86,11 @@ type EnvDefSpec<NODETYPE: NodeType> = {|
 
     // This function returns an object representing the DOM structure to be
     // created when rendering the defined LaTeX function.
-    // TODO: Port buildHTML to flow and make the return type explicit.
-    htmlBuilder: (group: ParseNode<NODETYPE>, options: Options) => *,
+    htmlBuilder: (group: ParseNode<NODETYPE>, options: Options) => HtmlDomNode,
 
     // This function returns an object representing the MathML structure to be
     // created when rendering the defined LaTeX function.
-    // TODO: Port buildMathML to flow and make the return type explicit.
-    mathmlBuilder: (group: ParseNode<NODETYPE>, options: Options) => *,
+    mathmlBuilder: (group: ParseNode<NODETYPE>, options: Options) => MathNode,
 |};
 
 export default function defineEnvironment<NODETYPE: NodeType>({
diff --git a/src/defineFunction.js b/src/defineFunction.js
index 44b0c70c..878f7661 100644
--- a/src/defineFunction.js
+++ b/src/defineFunction.js
@@ -2,13 +2,15 @@
 import {groupTypes as htmlGroupTypes} from "./buildHTML";
 import {groupTypes as mathmlGroupTypes} from "./buildMathML";
 import {checkNodeType} from "./ParseNode";
+import domTree from "./domTree";
 
 import type Parser from "./Parser";
-import type ParseNode from "./ParseNode";
-import type {NodeType, NodeValue} from "./ParseNode";
+import type ParseNode, {NodeType, NodeValue} from "./ParseNode";
 import type Options from "./Options";
 import type {ArgType, BreakToken, Mode} from "./types";
+import type {HtmlDomNode} from "./domTree";
 import type {Token} from "./Token";
+import type {MathNode, TextNode} from "./mathMLTree";
 
 /** Context provided to function handlers for error messages. */
 export type FunctionContext = {|
@@ -104,13 +106,16 @@ type FunctionDefSpec<NODETYPE: NodeType> = {|
 
     // This function returns an object representing the DOM structure to be
     // created when rendering the defined LaTeX function.
-    // TODO: Make return type explicit.
-    htmlBuilder?: (group: ParseNode<NODETYPE>, options: Options) => *,
+    htmlBuilder?: (group: ParseNode<NODETYPE>, options: Options) => HtmlDomNode,
 
+    // TODO: Currently functions/op.js returns documentFragment. Refactor it
+    // and update the return type of this function.
     // This function returns an object representing the MathML structure to be
     // created when rendering the defined LaTeX function.
-    // TODO: Make return type explicit.
-    mathmlBuilder?: (group: ParseNode<NODETYPE>, options: Options) => *,
+    mathmlBuilder?: (
+        group: ParseNode<NODETYPE>,
+        options: Options,
+    ) => MathNode | TextNode | domTree.documentFragment,
 |};
 
 /**
diff --git a/src/functions/op.js b/src/functions/op.js
index dbe751cb..326ee2fb 100644
--- a/src/functions/op.js
+++ b/src/functions/op.js
@@ -216,6 +216,10 @@ const mathmlBuilder = (group, options) => {
         const operator = new mathMLTree.MathNode("mo",
             [mml.makeText("\u2061", "text")]);
 
+        // TODO: Refactor to not return an HTML DOM object from MathML builder
+        // or refactor documentFragment to be standalone and explicitly reusable
+        // for both HTML and MathML DOM operations. In either case, update the
+        // return type of `mathBuilder` in `defineFunction` to accommodate.
         return new domTree.documentFragment([node, operator]);
     }
 
diff --git a/src/mathMLTree.js b/src/mathMLTree.js
index b483cdff..000b1514 100644
--- a/src/mathMLTree.js
+++ b/src/mathMLTree.js
@@ -29,7 +29,7 @@ export type MathNodeType =
  * constructor requires the type of node to create (for example, `"mo"` or
  * `"mspace"`, corresponding to `<mo>` and `<mspace>` tags).
  */
-class MathNode {
+export class MathNode {
     type: MathNodeType;
     attributes: {[string]: string};
     children: (MathNode | TextNode)[];
@@ -114,7 +114,7 @@ class MathNode {
 /**
  * This node represents a piece of text.
  */
-class TextNode {
+export class TextNode {
     text: string;
 
     constructor(text: string) {