Clean up API documentation; rename to eliminate reference to old implementation

2 files changed, 34 insertions, 45 deletions

diff --git a/pyxb/binding/basis.py b/pyxb/binding/basis.py
index fa23f54..63f9db4 100644
--- a/pyxb/binding/basis.py
+++ b/pyxb/binding/basis.py
@@ -1672,7 +1672,7 @@ class complexTypeDefinition (_TypeBinding_mixin, utility._DeconflictSymbols_mixi
     _ReservedSymbols = _TypeBinding_mixin._ReservedSymbols.union(set([ 'wildcardElements', 'wildcardAttributeMap',
                              'xsdConstraintsOK', 'content', 'append', 'extend', 'value', 'reset' ]))
 
-    # None, or a reference to a ContentModel instance that defines how to
+    # None, or a reference to a ParticleModel instance that defines how to
     # reduce a DOM node list to the body of this element.
     _ContentModel = None
 
@@ -1730,7 +1730,7 @@ class complexTypeDefinition (_TypeBinding_mixin, utility._DeconflictSymbols_mixi
         model, C{None} is returned.
 
         The base class implementation uses the
-        L{content.ContentModel.validate} method.  Subclasses may desire to
+        L{content.ParticleModel.validate} method.  Subclasses may desire to
         override this in cases where the desired order is not maintained by
         model interpretation (for example, when an "all" model is used and the
         original element order is desired).  See L{__childrenForDOM} as an
@@ -1904,7 +1904,7 @@ class complexTypeDefinition (_TypeBinding_mixin, utility._DeconflictSymbols_mixi
         else:
             self.__setContent(None)
 
-    __stateStack = None
+    __modelState = None
     def reset (self):
         """Reset the instance.
 
@@ -1919,7 +1919,7 @@ class complexTypeDefinition (_TypeBinding_mixin, utility._DeconflictSymbols_mixi
         for eu in self._ElementMap.values():
             eu.reset(self)
         if self._ContentModel is not None:
-            self.__stateStack = self._ContentModel.stateStack()
+            self.__modelState = self._ContentModel.newState()
         return self
 
     @classmethod
@@ -2033,7 +2033,7 @@ class complexTypeDefinition (_TypeBinding_mixin, utility._DeconflictSymbols_mixi
                 return self
         if self._isNil() and not self._IsSimpleTypeContent():
             raise pyxb.ExtraContentError('%s: Content %s present in element with xsi:nil' % (type(self), value))
-        if maybe_element and (self.__stateStack is not None):
+        if maybe_element and (self.__modelState is not None):
             # Allows element content.
             if not require_validation:
                 if element_use is not None:
@@ -2045,7 +2045,7 @@ class complexTypeDefinition (_TypeBinding_mixin, utility._DeconflictSymbols_mixi
                     return self
             else:
                 #print 'SSStep %s %s' % (value, element_use)
-                ( consumed, underflow_exc ) = self.__stateStack.step(self, value, element_use)
+                ( consumed, underflow_exc ) = self.__modelState.step(self, value, element_use)
                 if consumed:
                     return self
         # If what we have is element content, we can't accept it, either
@@ -2107,8 +2107,8 @@ class complexTypeDefinition (_TypeBinding_mixin, utility._DeconflictSymbols_mixi
         return (cls._CT_MIXED == cls._ContentTypeTag)
     
     def _postDOMValidate (self):
-        if self._PerformValidation() and (not self._isNil()) and (self.__stateStack is not None):
-            self.__stateStack.verifyComplete()
+        if self._PerformValidation() and (not self._isNil()) and (self.__modelState is not None):
+            self.__modelState.verifyComplete()
             self._validateAttributes()
         return self
 
diff --git a/pyxb/binding/content.py b/pyxb/binding/content.py
index 86688e2..252e973 100644
--- a/pyxb/binding/content.py
+++ b/pyxb/binding/content.py
@@ -21,16 +21,7 @@ the Python field in which the values are stored.  They also provide the
 low-level interface to set and get the corresponding values in a binding
 instance.
 
-L{ContentModelTransition}, L{ContentModelState}, and L{ContentModel} are used
-to store a deterministic finite automaton which is used to translate between
-binding instances and other representations (e.g., DOM nodes)
-
-L{ModelGroupAllAlternative} and L{ModelGroupAll} represent special nodes in
-the DFA that support a model group with compositor "all" in a way that does
-not result in an exponential state explosion in the DFA.
-
-L{DFAStack} and its related internal classes are used in stream-based
-processing of content.
+@todo: Document new content model
 
 L{Wildcard} holds content-related information used in the content model.
 """
@@ -54,7 +45,7 @@ class ContentState_mixin (pyxb.cscRoot):
     def contentModel (self):
         """Get the model associated with the state.
         
-        @return The L{ContentModel_mixin} instance for which this instance
+        @return: The L{ContentModel_mixin} instance for which this instance
         monitors state.  The value is C{None} if this is a non-aggregate state
         object like an L{ElementUse} or L{Wildcard}.
         """
@@ -67,22 +58,22 @@ class ContentState_mixin (pyxb.cscRoot):
         This method must not throw any non-catastrophic exceptions; general
         failures should be transformed to a C{False} return value.
 
-        @param particle_state The L{ParticleState} instance serving as the
+        @param particle_state: The L{ParticleState} instance serving as the
         parent to this state.  The implementation must inform that state when
         the proposed value completes the content model.
 
-        @param instance An instance of a subclass of
+        @param instance: An instance of a subclass of
         {basis.complexTypeDefinition}, into which the provided value will be
         stored if it is consistent with the current model state.
 
-        @param value The value that is being validated against the state.
+        @param value: The value that is being validated against the state.
 
-        @param element_use An optional L{ElementUse} instance that specifies
+        @param element_use: An optional L{ElementUse} instance that specifies
         the element to which the value corresponds.  This will be available
         when the value is extracted by parsing a document, but will be absent
         if the value was passed as a constructor positional parameter.
 
-        @return C{True} if the value was successfully matched against the
+        @return: C{True} if the value was successfully matched against the
         state.  C{False} if the value did not match against the state."""
         raise Exception('ContentState_mixin.accepts not implemented in %s' % (type(self),))
 
@@ -93,9 +84,9 @@ class ContentState_mixin (pyxb.cscRoot):
         Normally this is used when an intermediate content model must reset
         itself to permit alternative models to be evaluated.
 
-        @param sub_state the state that was unable to accept a value
+        @param sub_state: the state that was unable to accept a value
 
-        @param particle_ok C{True} if the particle that rejected the value is
+        @param particle_ok: C{True} if the particle that rejected the value is
         in an accepting terminal state
 
         """
@@ -112,7 +103,7 @@ class ContentState_mixin (pyxb.cscRoot):
         content model should produce the corresponding exception (generally,
         L{MissingContentError}).
 
-        @param parent_particle_state the L{ParticleState} for which this state
+        @param parent_particle_state: the L{ParticleState} for which this state
         is the term.
         """
         pass
@@ -124,7 +115,7 @@ class ContentModel_mixin (pyxb.cscRoot):
         """Return a L{ContentState_mixin} instance that will validate the
         state of this model component.
 
-        @param parent_particle_state The L{ParticleState} instance for which
+        @param parent_particle_state: The L{ParticleState} instance for which
         this instance is a term.  C{None} for the top content model of a
         complex data type.
         """
@@ -161,13 +152,13 @@ class ContentModel_mixin (pyxb.cscRoot):
         orders those letters in a way that satisfies the regular expression
         expressed in the model.  Both are changed as a result of a successful
         validation; both remain unchanged if the validation failed.  In
-        recursing, implementers may assume that C{output_sequence} is monotonic:
-        its length remains unchanged after an invocation iff the symbol set
-        also remains unchanged.  The L{_validateCloneSymbolSet},
-        L{_validateCloneOutputPath}, and L{_validateReplaceResults} methods
-        are available to help preserve this behavior.
+        recursing, implementers may assume that C{output_sequence} is
+        monotonic: its length remains unchanged after an invocation iff the
+        symbol set also remains unchanged.  The L{_validateCloneSymbolSet},
+        L{_validateCloneOutputSequence}, and L{_validateReplaceResults}
+        methods are available to help preserve this behavior.
 
-        @param symbol_set A map from L{ElementUse} instances to a list of
+        @param symbol_set: A map from L{ElementUse} instances to a list of
         values.  The order of the values corresponds to the order in which
         they should appear.  A key of C{None} identifies values that are
         stored as wildcard elements.  Values are removed from the lists as
@@ -175,16 +166,14 @@ class ContentModel_mixin (pyxb.cscRoot):
         removed from the map.  Thus an empty dictionary is the indicator that
         no more symbols are available.
 
-        @param output_sequence A mutable list to which should be appended
+        @param output_sequence: A mutable list to which should be appended
         tuples C{( eu, val )} where C{eu} is an L{ElementUse} from the set of
         symbol keys, and C{val} is a value from the corresponding list.  A
         document generated by producing the elements in the given order is
         expected to validate.
 
-        @return C{True} if the model validates: in this case the symbol set
-        and output sequence have been updated.  C{False} if the model
-        requirements cannot be met by the available symbols.  In this case
-        C{symbol_set} and C{output_sequence} must be unchanged.
+        @return: C{True} iff the model validates.  C{symbol_set} and
+        C{output_path} must be unmodified if returns C{False}.
         """
         raise Exception('ContentState_mixin._validate not implemented in %s' % (type(self),))
 
@@ -851,18 +840,18 @@ class ParticleState (pyxb.cscRoot):
         the particle's maximum occurrence limit is checked; if not, and the
         particle has a parent state, it is informed of the failure.
 
-        @param instance An instance of a subclass of
+        @param instance: An instance of a subclass of
         {basis.complexTypeDefinition}, into which the provided value will be
         stored if it is consistent with the current model state.
 
-        @param value The value that is being validated against the state.
+        @param value: The value that is being validated against the state.
 
-        @param element_use An optional L{ElementUse} instance that specifies
+        @param element_use: An optional L{ElementUse} instance that specifies
         the element to which the value corresponds.  This will be available
         when the value is extracted by parsing a document, but will be absent
         if the value was passed as a constructor positional parameter.
 
-        @return C{( consumed, underflow_exc )} A tuple where the first element
+        @return: C{( consumed, underflow_exc )} A tuple where the first element
         is C{True} iff the provided value was accepted in the current state.
         When this first element is C{False}, the second element will be
         C{None} if the particle's occurrence requirements have been met, and
@@ -871,7 +860,7 @@ class ParticleState (pyxb.cscRoot):
         context, the caller may raise this exception, or may try an
         alternative content model.
 
-        @raise L{pyxb.UnexpectedElementError} if the value satisfies the particle,
+        @raise pyxb.UnexpectedElementError: if the value satisfies the particle,
         but having done so exceeded the allowable number of instances of the
         term.
         """
@@ -928,7 +917,7 @@ class ParticleModel (ContentModel_mixin):
         self.__minOccurs = min_occurs
         self.__maxOccurs = max_occurs
 
-    def stateStack (self):
+    def newState (self):
         return ParticleState(self)
 
     def validate (self, symbol_set):