From bb557938bd06e727216cb4cade97a7b02c9cb36e Mon Sep 17 00:00:00 2001
From: Khaled Hosny <khaled@aliftype.com>
Date: Wed, 14 Feb 2024 02:46:13 +0200
Subject: [PATCH] [otlLib] Document buildMathTable

---
 Lib/fontTools/otlLib/builder.py | 93 +++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)

diff --git a/Lib/fontTools/otlLib/builder.py b/Lib/fontTools/otlLib/builder.py
index 7d9b99b55..61b671f6e 100644
--- a/Lib/fontTools/otlLib/builder.py
+++ b/Lib/fontTools/otlLib/builder.py
@@ -2922,6 +2922,99 @@ def buildMathTable(
     vertGlyphAssembly=None,
     horizGlyphAssembly=None,
 ):
+    """
+    Add a 'MATH' table to 'ttFont'.
+
+    'constants' is a dictionary of math constants. The keys are the constant
+    names from the MATH table specification (with capital first letter), and the
+    values are the constant values as numbers.
+
+    'italicsCorrections' is a dictionary of italic corrections. The keys are the
+    glyph names, and the values are the italic corrections as numbers.
+
+    'topAccentAttachments' is a dictionary of top accent attachments. The keys
+    are the glyph names, and the values are the top accent horizontal positions
+    as numbers.
+
+    'extendedShapes' is a set of extended shape glyphs.
+
+    'mathKerns' is a dictionary of math kerns. The keys are the glyph names, and
+    the values are dictionaries. The keys of these dictionaries are the side
+    names ('TopRight', 'TopLeft', 'BottomRight', 'BottomLeft'), and the values
+    are tuples of two lists. The first list contains the correction heights as
+    numbers, and the second list contains the kern values as numbers.
+
+    'minConnectorOverlap' is the minimum connector overlap as a number.
+
+    'vertGlyphVariants' is a dictionary of vertical glyph variants. The keys are
+    the glyph names, and the values are tuples of glyph name and full advance height.
+
+    'horizGlyphVariants' is a dictionary of horizontal glyph variants. The keys
+    are the glyph names, and the values are tuples of glyph name and full
+    advance width.
+
+    'vertGlyphAssembly' is a dictionary of vertical glyph assemblies. The keys
+    are the glyph names, and the values are tuples of assembly parts and italics
+    correction. The assembly parts are tuples of glyph name, flags, start
+    connector length, end connector length, and full advance height.
+
+    'horizGlyphAssembly' is a dictionary of horizontal glyph assemblies. The
+    keys are the glyph names, and the values are tuples tuples of assembly parts
+    and italics correction. The assembly parts are tuples of glyph name, flags,
+    start connector length, end connector length, and full advance width.
+
+    Where a number is expected, an integer or a float can be used. The floats
+    will be rounded.
+
+    Example::
+
+        constants = {
+            "ScriptPercentScaleDown": 70,
+            "ScriptScriptPercentScaleDown": 50,
+            "DelimitedSubFormulaMinHeight": 24,
+            "DisplayOperatorMinHeight": 60,
+            ...
+        }
+        italicsCorrections = {
+            "fitalic-math": 100,
+            "fbolditalic-math": 120,
+            ...
+        }
+        topAccentAttachments = {
+            "circumflexcomb": 500,
+            "acutecomb": 400,
+            "A": 300,
+            "B": 340,
+            ...
+        }
+        extendedShapes = {"parenleft", "parenright", ...}
+        mathKerns = {
+            "A": {
+                "TopRight": ([-50, -100], [10, 20, 30]),
+                "TopLeft": ([50, 100], [10, 20, 30]),
+                ...
+            },
+            ...
+        }
+        vertGlyphVariants = {
+            "parenleft": [("parenleft", 700), ("parenleft.size1", 1000), ...],
+            "parenright": [("parenright", 700), ("parenright.size1", 1000), ...],
+            ...
+        }
+        vertGlyphAssembly = {
+            "braceleft": [
+                (
+                    ("braceleft.bottom", 0, 0, 200, 500),
+                    ("braceleft.extender", 1, 200, 200, 200)),
+                    ("braceleft.middle", 0, 100, 100, 700),
+                    ("braceleft.extender", 1, 200, 200, 200),
+                    ("braceleft.top", 0, 200, 0, 500),
+                ),
+                100,
+            ],
+            ...
+        }
+    """
     glyphMap = ttFont.getReverseGlyphMap()
 
     ttFont["MATH"] = math = ttLib.newTable("MATH")