Document new pens

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

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)

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()

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]

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)