Documentation cleanup

7 files changed, 38 insertions, 33 deletions

diff --git a/doc/arch_binding.txt b/doc/arch_binding.txt
index af886dc..56e9a6c 100644
--- a/doc/arch_binding.txt
+++ b/doc/arch_binding.txt
@@ -91,7 +91,7 @@ result of collision with names from Python keywords, public class names, and
 public field or method names in the class.  The
 :api:`pyxb.utils.utility._DeconflictSymbols_mixin` is used to refine the set
 of type-specific public names.  If you customize a generated binding class by
-extending from it, you must specific your own class variable
+extending from it, you must specify your own class variable
 ``_ReservedSymbols`` with a value that is the union of your symbols and those
 of the superclass(es) (see :api:`pyxb.utils.utility._DeconflictSymbols_mixin`
 for details).
@@ -245,9 +245,9 @@ Complex Type Definitions
 type definitions record maps that specify :api:`attribute
 <pyxb.binding.content.AttributeUse>` and :api:`element
 <pyxb.binding.content.ElementUse>` use structures to record the attributes and
-elements that comprise the type.  The values are stored in class members, and
-when using the default code generation template are managed through accessor
-methods.
+elements that comprise the type.  Each such structure is stored as a private
+class field and is used by Python properties to provide access to element and
+attribute values in a binding instance.
 
 The base :api:`pyxb.binding.basis.complexTypeDefinition` class provides the
 infrastructure to identify the appropriate attribute or element given an XML
@@ -280,8 +280,7 @@ are disambiguated, and a Python property is defined to retrieve and set the
 element value.
 
 When the content model permits multiple occurrences of the element, its value
-is a Python list.  In that case, a third accessor function ``appendBar`` will
-add a new instance to that list.
+is a Python list.
 
 Attributes
 ^^^^^^^^^^
@@ -327,9 +326,9 @@ produces the following output:
 
 Note that it was necessary to indicate that the second member (``complex``) of
 the ``numbers`` element needs to be wrapped in an instance of the appropriate
-complex type.  Consequently, it was necessary to add the call to ``value()``
-on the value of ``v.complex`` in order to get a valid Python numeric value.
-This was not necessary for ``v.simple`` or ``v.attribute``.
+complex type.  Similarly, it was necessary to add the call to ``value()`` on
+the value of ``v.complex`` in order to get a valid Python numeric value.  This
+was not necessary for ``v.simple`` or ``v.attribute``.
 
 Mixed and Element-Only Content
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -351,11 +350,12 @@ non-element content that belong to the instance.
 Elements
 --------
 
-Unlike the bindings for schema type definitions, bindings corresponding to XML
-Schema element declarations are represented as instances of the
-:api:`pyxb.binding.basis.element` class.  The instances can be used to create
-new binding instances that are associated with the element.  Elements are used
-in the content model to identify transitions through a finite automaton.
+Unlike the bindings for schema type definitions, which are represented as
+Python classes, bindings corresponding to XML Schema element declarations are
+represented as instances of the :api:`pyxb.binding.basis.element` class.  The
+instances can be used to create new binding instances that are associated with
+the element.  Elements are used in the content model to identify transitions
+through a finite automaton.
 
 You can use elements just like types in that they are invokable, with
 arguments corresponding to the arguments of the constructor of the
diff --git a/doc/arch_content.txt b/doc/arch_content.txt
index cae73d1..58641c5 100644
--- a/doc/arch_content.txt
+++ b/doc/arch_content.txt
@@ -154,13 +154,13 @@ path so far comprises the member elements added to the instance.
 The need for a stack of states comes when automaton execution reaches a
 transition that involves an :api:`"all" model group
 <pyxb.binding.content.ModelGroupAll>`.  Evaluation of such a transition
-requires suspending the parent execution and continuing with the evaluation of
-the automata that represent alternatives in the model group.
+requires suspending the parent automaton execution and continuing with the
+evaluation of the automata that represent alternatives in the model group.
 
 Generation With Automata
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Automata-based parsing is also used to validate that the content of a binding
+Automaton evaluation is also used to validate that the content of a binding
 instance is consistent with type's content model, and to determine a sequence
 of contained elements that define a valid path through the automaton.  This
 technique is used to create a valid DOM document from a binding instance.
diff --git a/doc/arch_namespaces.txt b/doc/arch_namespaces.txt
index d8ab01e..923b80d 100644
--- a/doc/arch_namespaces.txt
+++ b/doc/arch_namespaces.txt
@@ -135,13 +135,16 @@ Expanded Names
 An :api:`pyxb.namespace.ExpandedName` instance couples a local name with
 (optionally) a namespace, resulting in a QName.  This class also integrates
 with namespace categories, permitting lookup of the object with its name in a
-specific category by using the category name as a method.  For example::
+specific category by using the category name as a method.  For example, the
+following two expressions are equivalent::
 
+  # Short-hand method
   en.typeDefinition()
+  # Detailed equivalent
   en.namespace().categoryMap('typeDefinition').get(en.localName())
 
-produces the type definition with the given name, or ``None`` if there is no
-such definition.  The short-hand method interface works for any category
+Both produce the type definition with the given name, or ``None`` if there is
+no such definition.  The short-hand method interface works for any category
 defined within the expanded name's namespace; it is not limited to the
 standard set of component categories.
 
@@ -152,8 +155,8 @@ In this version of PyXB, the hash codes and comparison methods for
 :api:`ExpandedName <pyxb.namespace.ExpandedName>` have been overridden so that
 an expanded name with no namespace is treated equivalently to the string value
 of the local name.  This simplified management of default namespace lookups in
-earlier versions of PyXB, but may no longer be necessary; use of this feature
-is discouraged.
+earlier versions of PyXB, but may no longer be necessary; reliance on this
+feature is discouraged.
 
 Namespace Context
 -----------------
@@ -313,9 +316,9 @@ The contents of the namespace archive are:
     origins may be associated with a single module record
 
   - the set of :api:`pyxb.namespace.Namespace` instances that were referenced
-    by A.  This includes namespaces that were imported into one of the origin
-    objects, as well as those that were incorporated simply through reference
-    to an object in a declared namespace
+    by ``A``.  This includes namespaces that were imported into one of the
+    origin objects, as well as those that were incorporated simply through
+    reference to an object in a declared namespace
 
 - The objects within the namespace that were defined by the various origins
 
diff --git a/doc/examples.txt b/doc/examples.txt
index 54d7736..a202826 100644
--- a/doc/examples.txt
+++ b/doc/examples.txt
@@ -117,7 +117,7 @@ work with:
    messages, since PyXB's WSDL support does not currently generate them from
    the operation messages.
 
- :file:`genbindings.sh` applies changes to the WSDL after retrieving it and
+:file:`genbindings.sh` applies changes to the WSDL after retrieving it and
 prior to generating the bindings.
 
 A second complication is the need to burrow down through wildcard elements
diff --git a/doc/limitations.txt b/doc/limitations.txt
index 14efd97..9d5095a 100644
--- a/doc/limitations.txt
+++ b/doc/limitations.txt
@@ -48,14 +48,16 @@ Things That Don't Work
   provide access to unrecognized values through the
   :api:`pyxb.binding.basis.complexTypeDefinition.wildcardElements` method.
   Where the type of the node is recognized, it is converted to a Python
-  binding instance.  However, neither the namespace constraint nor process
-  contents attributes are applied.
+  binding instance; otherwise, the xml DOM instance is stored.  Neither the
+  namespace constraint nor process contents attributes of the wildcard are
+  applied.
 
 * `Wildcard attributes
   <http://www.w3.org/TR/xmlschema-1/#ag-attribute_wildcard>`_ are supported
   in the same sense as wildcard elements: no constraints are checked, and
   all are aggregated into the
   :api:`pyxb.binding.basis.complexTypeDefinition.wildcardAttributeMap`.
+  Values are uninterpreted Unicode strings.
 
 ...and probably never will
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/doc/maintref.txt b/doc/maintref.txt
index 14a096e..43289f4 100644
--- a/doc/maintref.txt
+++ b/doc/maintref.txt
@@ -126,10 +126,10 @@ Python class.
 class : [as an adjective] Refers to a characteristic of a Python class
 itself, shared among all instances.
 
-field : Refers to a named attribute of a Python class.  When the attribute
-holds a value, it is an "instance (class) variable" or "instance field".
-When it holds a reference to an invokable object, it is an "instance (class)
-method".
+field : Refers to a named attribute of a Python object (class).  When the
+attribute holds a value, it is an "instance (class) variable" or "instance
+(class) field".  When it holds a reference to an invokable object, it is an
+"instance (class) method".
 
 Use of new-style classes
 ========================
diff --git a/doc/userref_usebind.txt b/doc/userref_usebind.txt
index b3ffa46..0d9f4bc 100644
--- a/doc/userref_usebind.txt
+++ b/doc/userref_usebind.txt
@@ -38,7 +38,7 @@ As described in :ref:`bindingModel`, binding classes corresponding to simple
 types extend the underlying Python type (such as ``str`` or ``int``), and
 add XML-specific information like the canonical representation of the value
 in `Unicode <http://www.unicode.org/>`_, which is the natural representation
-XML text.  These classes also maintain a set of facets that constrain the
+as XML text.  These classes also maintain a set of facets that constrain the
 values that can be stored as instances when validation is active.  Binding
 classes for complex types have constructors that parse positional and
 keyword parameters to determine the appropriate element or attribute to