From c2033cb0958a6217778cf9ddb19d01d80f7adbb3 Mon Sep 17 00:00:00 2001
From: Behdad Esfahbod <behdad@behdad.org>
Date: Sun, 26 Feb 2017 10:41:11 -0800
Subject: [PATCH] Document new pens

---
 Lib/fontTools/pens/momentsPen.py    |  2 ++
 Lib/fontTools/pens/recordingPen.py  |  7 ++++++-
 Lib/fontTools/pens/statisticsPen.py | 12 ++++++++++++
 Lib/fontTools/pens/teePen.py        |  5 +++++
 NEWS.rst                            |  1 +
 5 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/Lib/fontTools/pens/momentsPen.py b/Lib/fontTools/pens/momentsPen.py
index 11d3492ca..b83102ccc 100644
--- a/Lib/fontTools/pens/momentsPen.py
+++ b/Lib/fontTools/pens/momentsPen.py
@@ -1,3 +1,5 @@
+"""Pen calculating 0th, 1st, and 2nd moments of area of glyph shapes.
+This is low-level, autogenerated pen. Use statisticsPen instead."""
 from __future__ import print_function, division, absolute_import
 from fontTools.misc.py23 import *
 from fontTools.pens.basePen import BasePen
diff --git a/Lib/fontTools/pens/recordingPen.py b/Lib/fontTools/pens/recordingPen.py
index c21972217..a196d3ff2 100644
--- a/Lib/fontTools/pens/recordingPen.py
+++ b/Lib/fontTools/pens/recordingPen.py
@@ -1,3 +1,4 @@
+"""Pen recording operations that can be accessed or replayed."""
 from __future__ import print_function, division, absolute_import
 from fontTools.misc.py23 import *
 from fontTools.pens.basePen import AbstractPen
@@ -7,6 +8,11 @@ __all__ = ["RecordingPen"]
 
 
 class RecordingPen(AbstractPen):
+	"""Pen recording operations that can be accessed or replayed.
+
+	The recording can be accessed as pen.value; or replayed using
+	pen.replay(otherPen)."""
+
 	def __init__(self):
 		self.value = []
 	def moveTo(self, p0):
@@ -23,7 +29,6 @@ class RecordingPen(AbstractPen):
 		self.value.append(('endPath', ()))
 	def addComponent(self, glyphName, transformation):
 		self.value.append(('addComponent', (glyphName, transformation)))
-
 	def replay(self, pen):
 		for operator,operands in self.value:
 			getattr(pen, operator)(*operands)
diff --git a/Lib/fontTools/pens/statisticsPen.py b/Lib/fontTools/pens/statisticsPen.py
index 763030785..7c2e85c83 100644
--- a/Lib/fontTools/pens/statisticsPen.py
+++ b/Lib/fontTools/pens/statisticsPen.py
@@ -1,3 +1,5 @@
+"""Pen calculating area, center of mass, variance and standard-deviation,
+covariance and correlation, and slant, of glyph shapes."""
 from __future__ import print_function, division, absolute_import
 from fontTools.misc.py23 import *
 import math
@@ -8,6 +10,16 @@ __all__ = ["StatisticsPen"]
 
 class StatisticsPen(MomentsPen):
 
+	"""Pen calculating area, center of mass, variance and
+	standard-deviation, covariance and correlation, and slant,
+	of glyph shapes.
+
+	Note that all the calculated values are 'signed'. Ie. if the
+	glyph shape is self-intersecting, the values are not correct
+	(but well-defined). As such, area will be negative if contour
+	directions are clockwise.  Moreover, variance might be negative
+	if the shapes are self-intersecting in certain ways."""
+
 	def __init__(self, glyphset=None):
 		MomentsPen.__init__(self, glyphset=glyphset)
 		self.__zero()
diff --git a/Lib/fontTools/pens/teePen.py b/Lib/fontTools/pens/teePen.py
index 31aba7b62..ce22c850e 100644
--- a/Lib/fontTools/pens/teePen.py
+++ b/Lib/fontTools/pens/teePen.py
@@ -1,3 +1,4 @@
+"""Pen multiplexing drawing to one or more pens."""
 from __future__ import print_function, division, absolute_import
 from fontTools.misc.py23 import *
 from fontTools.pens.basePen import AbstractPen
@@ -7,6 +8,10 @@ __all__ = ["TeePen"]
 
 
 class TeePen(AbstractPen):
+	"""Pen multiplexing drawing to one or more pens.
+
+	Use either as TeePen(pen1, pen2, ...) or TeePen(iterableOfPens)."""
+
 	def __init__(self, *pens):
 		if len(pens) == 1:
 			pens = pens[0]
diff --git a/NEWS.rst b/NEWS.rst
index 602d6927a..9e2393d37 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -1,3 +1,4 @@
+- New pens: MomentsPen, StatisticsPen, RecordingPen, and TeePen.
 - [varLib] designspace.load() now returns a dictionary, instead of a tuple,
   and supports <axes> element (#864)