fontTools.misc.* documentation, part 2 (#1981)

* Document misc.filenames
* Document misc.fixedTools
* Document misc.intTools
* Document misc.loggingTools
* Document misc.macCreatorType
* Document misc.macRes
* Document misc.plistlib

Doc/source/misc/filenames.rst

@@ -1,8 +1,7 @@
-#########
-filenames
-#########
+##########################################################
+filenames: Implements UFO User Name to File Name Algorithm
+##########################################################
 
 .. automodule:: fontTools.misc.filenames
-   :inherited-members:
-   :members:
+   :members: userNameToFileName
    :undoc-members:

Doc/source/misc/fixedTools.rst

@@ -1,6 +1,6 @@
-##########
-fixedTools
-##########
+######################################################
+fixedTools: Tools for working with fixed-point numbers
+######################################################
 
 .. automodule:: fontTools.misc.fixedTools
    :inherited-members:

Doc/source/misc/index.rst

@@ -21,6 +21,7 @@ utilities by fontTools, but some of which may be more generally useful.
    loggingTools
    macCreatorType
    macRes
+   plistlib
    psCharStrings
    psLib
    psOperators

Doc/source/misc/intTools.rst

@@ -1,8 +1,6 @@
-########
-intTools
-########
+###############################################
+intTools: Tools for working with integer values
+###############################################
 
 .. automodule:: fontTools.misc.intTools
-   :inherited-members:
    :members:
-   :undoc-members:

Doc/source/misc/loggingTools.rst

@@ -1,8 +1,7 @@
-############
-loggingTools
-############
+###################################################################
+loggingTools: tools for interfacing with the Python logging package
+###################################################################
 
 .. automodule:: fontTools.misc.loggingTools
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/misc/macCreatorType.rst

@@ -1,8 +1,9 @@
-##############
-macCreatorType
-##############
+##############################################################
+macCreatorType: Functions for working with Mac file attributes
+##############################################################
+
+This module requires the `xattr <https://pypi.org/project/xattr/>`_ module
+to be installed in order to function correctly.
 
 .. automodule:: fontTools.misc.macCreatorType
-   :inherited-members:
    :members:
-   :undoc-members:

Doc/source/misc/macRes.rst

@@ -1,8 +1,11 @@
-######
-macRes
-######
+############################################
+macRes: Tools for reading Mac resource forks
+############################################
+
+Classic Mac OS files are made up of two parts - the "data fork" which contains the file contents proper, and the "resource fork" which contains a number of structured data items called "resources". Some fonts, such as Mac "font suitcases" and Type 1 LWFN fonts, still use the resource fork for this kind of structured data, and so to read them, fontTools needs to have access to resource forks.
+
+The Inside Macintosh volume `More Macintosh Toolbox <https://developer.apple.com/library/archive/documentation/mac/pdf/MoreMacintoshToolbox.pdf#page=34>`_ explains the structure of resource and data forks.
 
 .. automodule:: fontTools.misc.macRes
-   :inherited-members:
-   :members:
-   :undoc-members:
+   :members: ResourceReader, Resource
+   :member-order: bysource

Doc/source/misc/plistlib.rst

@@ -0,0 +1,9 @@
+#########################################
+plistlib: Tools for handling .plist files
+#########################################
+
+.. automodule:: fontTools.misc.plistlib
+   :members: totree, fromtree, load, loads, dump, dumps
+
+.. autoclass:: fontTools.misc.plistlib.Data
+   :members:

Lib/fontTools/misc/filenames.py

@@ -1,19 +1,23 @@
 """
-User name to file name conversion based on the UFO 3 spec:
-http://unifiedfontobject.org/versions/ufo3/conventions/
-
-The code was copied from:
-https://github.com/unified-font-object/ufoLib/blob/8747da7/Lib/ufoLib/filenames.py
-
-Author: Tal Leming
-Copyright (c) 2005-2016, The RoboFab Developers:
-	Erik van Blokland
-	Tal Leming
-	Just van Rossum
+This module implements the algorithm for converting between a "user name" -
+something that a user can choose arbitrarily inside a font editor - and a file
+name suitable for use in a wide range of operating systems and filesystems.
+
+The `UFO 3 specification <http://unifiedfontobject.org/versions/ufo3/conventions/>`_
+provides an example of an algorithm for such conversion, which avoids illegal
+characters, reserved file names, ambiguity between upper- and lower-case
+characters, and clashes with existing files.
+
+This code was originally copied from
+`ufoLib <https://github.com/unified-font-object/ufoLib/blob/8747da7/Lib/ufoLib/filenames.py>`_
+by Tal Leming and is copyright (c) 2005-2016, The RoboFab Developers:
+
+-	Erik van Blokland
+-	Tal Leming
+-	Just van Rossum
 """
 from fontTools.misc.py23 import basestring, unicode
 
-
 illegalCharacters = r"\" * + / : < > ? [ \ ] | \0".split(" ")
 illegalCharacters += [chr(i) for i in range(1, 32)]
 illegalCharacters += [chr(0x7F)]
@@ -27,54 +31,69 @@ class NameTranslationError(Exception):
 
 
 def userNameToFileName(userName, existing=[], prefix="", suffix=""):
-	"""
-	existing should be a case-insensitive list
-	of all existing file names.
-
-	>>> userNameToFileName("a") == "a"
-	True
-	>>> userNameToFileName("A") == "A_"
-	True
-	>>> userNameToFileName("AE") == "A_E_"
-	True
-	>>> userNameToFileName("Ae") == "A_e"
-	True
-	>>> userNameToFileName("ae") == "ae"
-	True
-	>>> userNameToFileName("aE") == "aE_"
-	True
-	>>> userNameToFileName("a.alt") == "a.alt"
-	True
-	>>> userNameToFileName("A.alt") == "A_.alt"
-	True
-	>>> userNameToFileName("A.Alt") == "A_.A_lt"
-	True
-	>>> userNameToFileName("A.aLt") == "A_.aL_t"
-	True
-	>>> userNameToFileName(u"A.alT") == "A_.alT_"
-	True
-	>>> userNameToFileName("T_H") == "T__H_"
-	True
-	>>> userNameToFileName("T_h") == "T__h"
-	True
-	>>> userNameToFileName("t_h") == "t_h"
-	True
-	>>> userNameToFileName("F_F_I") == "F__F__I_"
-	True
-	>>> userNameToFileName("f_f_i") == "f_f_i"
-	True
-	>>> userNameToFileName("Aacute_V.swash") == "A_acute_V_.swash"
-	True
-	>>> userNameToFileName(".notdef") == "_notdef"
-	True
-	>>> userNameToFileName("con") == "_con"
-	True
-	>>> userNameToFileName("CON") == "C_O_N_"
-	True
-	>>> userNameToFileName("con.alt") == "_con.alt"
-	True
-	>>> userNameToFileName("alt.con") == "alt._con"
-	True
+	"""Converts from a user name to a file name.
+
+	Takes care to avoid illegal characters, reserved file names, ambiguity between
+	upper- and lower-case characters, and clashes with existing files.
+
+	Args:
+		userName (str): The input file name.
+		existing: A case-insensitive list of all existing file names.
+		prefix: Prefix to be prepended to the file name.
+		suffix: Suffix to be appended to the file name.
+
+	Returns:
+		A suitable filename.
+
+	Raises:
+		NameTranslationError: If no suitable name could be generated.
+
+	Examples::
+
+		>>> userNameToFileName("a") == "a"
+		True
+		>>> userNameToFileName("A") == "A_"
+		True
+		>>> userNameToFileName("AE") == "A_E_"
+		True
+		>>> userNameToFileName("Ae") == "A_e"
+		True
+		>>> userNameToFileName("ae") == "ae"
+		True
+		>>> userNameToFileName("aE") == "aE_"
+		True
+		>>> userNameToFileName("a.alt") == "a.alt"
+		True
+		>>> userNameToFileName("A.alt") == "A_.alt"
+		True
+		>>> userNameToFileName("A.Alt") == "A_.A_lt"
+		True
+		>>> userNameToFileName("A.aLt") == "A_.aL_t"
+		True
+		>>> userNameToFileName(u"A.alT") == "A_.alT_"
+		True
+		>>> userNameToFileName("T_H") == "T__H_"
+		True
+		>>> userNameToFileName("T_h") == "T__h"
+		True
+		>>> userNameToFileName("t_h") == "t_h"
+		True
+		>>> userNameToFileName("F_F_I") == "F__F__I_"
+		True
+		>>> userNameToFileName("f_f_i") == "f_f_i"
+		True
+		>>> userNameToFileName("Aacute_V.swash") == "A_acute_V_.swash"
+		True
+		>>> userNameToFileName(".notdef") == "_notdef"
+		True
+		>>> userNameToFileName("con") == "_con"
+		True
+		>>> userNameToFileName("CON") == "C_O_N_"
+		True
+		>>> userNameToFileName("con.alt") == "_con.alt"
+		True
+		>>> userNameToFileName("alt.con") == "alt._con"
+		True
 	"""
 	# the incoming name must be a unicode string
 	if not isinstance(userName, unicode):