Simplify doc summaries

mdboom · mdboom · commit 565f42a75964 · 2015-11-04T15:50:38.000-05:00
diff --git a/docstrings/bitmap.py b/docstrings/bitmap.py
@@ -34,7 +34,7 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 Bitmap__init__ = """
-A structure used to describe a bitmap or pixmap to the raster.
+Describes a bitmap raster.
 
 `Bitmap` supports the Python buffer interface, so it is easy to
 convert it to a Numpy array.  For example::
@@ -111,7 +111,7 @@
 """
 
 PIXEL_MODE = """
-Constants related to the pixel mode of bitmaps.
+Constants related to the pixel mode of `Bitmap`.
 
 - `MONO`: A monochrome bitmap, using 1 bit per pixel. Note that pixels
   are stored in most-significant order (MSB), which means that the
diff --git a/docstrings/bitmap_size.py b/docstrings/bitmap_size.py
@@ -34,8 +34,9 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 Bitmap_Size__init__ = """
-Models the metrics of a bitmap strike in a bitmap font. It is used for
-`Face.available_sizes`.
+The metrics of a bitmap strike in a bitmap `Face`.
+
+It is used for `Face.available_sizes`.
 """
 
 Bitmap_Size_height = """
diff --git a/docstrings/charmap.py b/docstrings/charmap.py
@@ -34,8 +34,9 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 CharMap__init__ = """
-A mapping from code points to glyph identifiers. Some font formats may
-provide several `CharMap` instances per font.
+A mapping from code points to glyph identifiers.
+
+Some font formats may provide several `CharMap` instances per font.
 
 Each face object owns zero or more charmaps, but only one of them can
 be ‘active’ and used by `Face.get_char_index` or `Face.load_char`.
diff --git a/docstrings/face.py b/docstrings/face.py
@@ -34,7 +34,7 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 Face__init__ = """
-A face object models a given typeface, in a given style.
+Models a given typeface, in a given style.
 
 Parameters
 ----------
@@ -711,7 +711,7 @@
 """
 
 FACE_FLAG = """
-A set of bit flags that give important information about the face.
+Bit flags for important metadata about a `Face`.
 
 - `SCALABLE`: Indicates that the face contains outline glyphs. This
   doesn't prevent bitmap strikes, i.e., a face can have both this and
@@ -786,7 +786,7 @@
 """
 
 STYLE_FLAG = """
-Bit flags to indicate the style of a given face.
+Bit flags indicating the style of a `Face`.
 
 - `ITALIC`: Indicates that a given face style is italic
   or oblique.
@@ -795,10 +795,11 @@
 """
 
 LOAD = """
-A flag indicating what to load for this glyph. The `LOAD` constants
-can be used to control the glyph loading process (e.g., whether the
-outline should be scaled, whether to load bitmaps or not, whether to
-hint the outline, etc).
+Indicates what to load for a glyph.
+
+The `LOAD` constants can be used to control the glyph loading process
+(e.g., whether the outline should be scaled, whether to load bitmaps
+or not, whether to hint the outline, etc).
 
 - `DEFAULT`: Corresponding to 0, this value is used as the default
   glyph load operation. In this case, the following happens:
@@ -932,7 +933,7 @@
 """
 
 SIZE_REQUEST_TYPE = """
-Modes for selecting the size of a bitmap font.
+Modes for selecting the size of a bitmap `Face`.
 
 - `NOMINAL`: The nominal size. The `Face.units_per_em` is used to
   determine both scaling values.
@@ -959,8 +960,8 @@
 """
 
 FSTYPE = """
-A list of bit flags indicating the embedding and subsetting
-restrictions with a font.
+Bit flags indicating the embedding and subsetting
+restrictions of a `Face`.
 
 - `INSTALLABLE_EMBEDDING`: Fonts with no fsType bit set may be
   embedded and permanently installed on the remote system by an
diff --git a/docstrings/glyph.py b/docstrings/glyph.py
@@ -34,7 +34,7 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 Glyph__init__ = """
-Contains information pertaining to a single glyph.
+Information pertaining to a single glyph.
 
 Notes
 -----
@@ -220,7 +220,7 @@
 """
 
 GLYPH_BBOX = """
-The mode how the values of `Glyph.get_cbox` are returned.
+Indicates how the values of `Glyph.get_cbox` are returned.
 
 - `UNSCALED`: Return unscaled font units.
 
@@ -234,10 +234,11 @@
 """
 
 GLYPH_FORMAT = """
-An enumeration type used to describe the format of a given glyph
-image. Note that this version of FreeType only supports two image
-formats, even though future font drivers will be able to register
-their own format.
+Describes the format of a given glyph image.
+
+Note that this version of FreeType only supports two image formats,
+even though future font drivers will be able to register their own
+format.
 
 - `NONE`: The value 0 is reserved.
 
@@ -259,7 +260,7 @@
 """
 
 RENDER_MODE = """
-A set of enumerations to select a bitmap renderer.
+Selects a `Bitmap` renderer.
 
 - `NORMAL`: This is the default render mode; it corresponds to 8-bit
   anti-aliased bitmaps.
diff --git a/docstrings/glyph_metrics.py b/docstrings/glyph_metrics.py
@@ -34,7 +34,7 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 Glyph_Metrics__init__ = """
-A structure used to model the metrics of a single glyph.
+Models the metrics of a single `Glyph`.
 
 Notes
 -----
diff --git a/docstrings/layout.py b/docstrings/layout.py
@@ -35,7 +35,7 @@
 
 
 Layout__init__ = """
-|freetypy| This class handles very simple layout of left-to-right text.
+|freetypy| Manages very simple layout of left-to-right text.
 
 Parameters
 ----------
diff --git a/docstrings/outline.py b/docstrings/outline.py
@@ -363,7 +363,7 @@ def cubic_to(self, a, b, c):
 """
 
 OUTLINE = """
-A set of bit flags to characterize an `Outline`.
+Bit flags to characterize an `Outline`.
 
 - `NONE`: Value 0 is reserved.
 
@@ -421,7 +421,7 @@ def cubic_to(self, a, b, c):
 """
 
 ORIENTATION = """
-Values to specify how an outline is oriented.
+Specifies how an `Outline` is oriented.
 
 - `TRUETYPE`: According to the TrueType specification, clockwise
   contours must be filled, and counter-clockwise ones must be
diff --git a/docstrings/sfntnames.py b/docstrings/sfntnames.py
@@ -34,7 +34,7 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 SfntNames__init__ = """
-A sequence of SFNT names in the face.
+A sequence of SFNT names in a `Face`.
 """
 
 SfntNames_get_name = """
diff --git a/docstrings/size.py b/docstrings/size.py
@@ -34,7 +34,7 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 Size__init__ = """
-A size object models a face object at a given size.
+A `Face` object at a given size.
 """
 
 Size_face = """
diff --git a/docstrings/subglyph.py b/docstrings/subglyph.py
@@ -59,7 +59,7 @@
 """
 
 SUBGLYPH_FLAG = """
-A list of constants used to describe subglyphs.
+Describes subglyphs.
 
 - `ARGS_ARE_WORDS`: If set, `SubGlyph.arg1` and `SubGlyph.arg2`
   are words, else bytes.
diff --git a/docstrings/truetype.py b/docstrings/truetype.py
@@ -35,7 +35,7 @@
 
 
 TT_PLATFORM = """
-A set of platform identifier codes.
+Platform identifier codes.
 
 - `APPLE_UNICODE`: Used by Apple to indicate a Unicode character map
   and/or name entry. See `TT_APPLE_ID` for corresponding ‘encoding_id’
@@ -144,9 +144,10 @@
 """
 
 TT_MAC_LANGID = """
-Possible values of the language identifier field in the name records
-of the TTF "name" table if the "platform" identifier code is
-`TT_PLATFORM.MACINTOSH`.
+Language identifier.
+
+Used in the name records of the TTF "name" table if the "platform"
+identifier code is `TT_PLATFORM.MACINTOSH`.
 """
 
 TT_MS_ID = """
@@ -176,13 +177,14 @@
 """
 
 TT_MS_LANGID = """
-Possible values of the language identifier field in the name records
-of the TTF "name" table if the "platform" identifier code is
-`TT_PLATFORM.MICROSOFT`.
+Language identifier.
+
+Used in in the name records of the TTF "name" table if the "platform"
+identifier code is `TT_PLATFORM.MICROSOFT`.
 """
 
 TT_NAME_ID = """
-Indicates the type of value stored in a `SfntName` record.
+The type of value stored in a `SfntName` record.
 
 - `COPYRIGHT`
 - `FONT_FAMILY`
diff --git a/docstrings/tt_header.py b/docstrings/tt_header.py
@@ -58,7 +58,7 @@
 """
 
 TT_HEADER_FLAGS = """
-|freetypy| Bitflags giving global information about the font.
+|freetypy| Bit flags for global information about a `Face`.
 
 - `BASELINE_AT_ZERO`: If set, the baselines for the font is at *y* = 0
   (that is, the *x*-axis)
@@ -123,7 +123,7 @@
 """
 
 TT_MAC_STYLE = """
-Bit flags indicating the style of the face.
+Bit flags for the style of the face.
 
 - `BOLD`
 
diff --git a/docstrings/tt_horiheader.py b/docstrings/tt_horiheader.py
@@ -68,7 +68,7 @@
 """
 
 TT_HoriHeader__init__ = """
-A structure used to model a TrueType horizontal header (‘hhea’).
+TrueType horizontal header (‘hhea’).
 """
 
 TT_HoriHeader_advance_width_max = """
diff --git a/docstrings/tt_os2.py b/docstrings/tt_os2.py
@@ -34,8 +34,7 @@
 from __future__ import print_function, unicode_literals, absolute_import
 
 TT_OS2__init__ = """
-Information about the TrueType font, used on OS/2 and Microsoft
-Windows.
+Inf about the TrueType font, used on OS/2 and Microsoft Windows.
 
 Note that we now support old Mac fonts which do not include an OS/2
 table.  In this case, the `version` field is always set to 0xFFFF.
@@ -323,7 +322,7 @@ class (either by a font designer or by some automated means) the
 """
 
 TT_FS_SELECTION = """
-Bitflag concerning the nature of the font patterns.
+Bit flag for font style.
 
 - `ITALIC`
 
diff --git a/docstrings/tt_pclt.py b/docstrings/tt_pclt.py
@@ -35,8 +35,9 @@
 
 
 TT_Pclt__init__ = """
-A structure used to model a TrueType PCLT table. All fields comply to
-the TrueType specification.
+TrueType PCLT table.
+
+All fields comply to the TrueType specification.
 
 This field is discouraged in OpenType and modern TrueType fonts, so it
 should be used sparingly and not assumed to be available.
diff --git a/docstrings/tt_postscript.py b/docstrings/tt_postscript.py
@@ -35,7 +35,7 @@
 
 
 TT_Postscript__init__ = """
-A TrueType PostScript table.
+TrueType PostScript table.
 """
 
 TT_Postscript_format_type = """
diff --git a/docstrings/tt_vertheader.py b/docstrings/tt_vertheader.py
@@ -68,7 +68,7 @@
 """
 
 TT_VertHeader__init__ = """
-A structure used to model a TrueType vertical header (‘vhea’).
+TrueType vertical header (‘vhea’).
 """
 
 TT_VertHeader_advance_height_max = """
