Merge pull request #335 from pllab/typos-and-docs

Adding documentation, fixing typos

Author: mdko

pyrtl/compilesim.py

@@ -21,7 +21,7 @@
 
 
 class DllMemInspector(collections.Mapping):
-    """Dictionary-like access to a hashmap in a CompiledSimulation."""
+    """ Dictionary-like access to a hashmap in a CompiledSimulation. """
 
     def __init__(self, sim, mem):
         self._aw = mem.addrwidth
@@ -229,10 +229,10 @@ def _sort_tuple(t):
             file.flush()
 
     def run(self, inputs):
-        """Run many steps of the simulation.
+        """ Run many steps of the simulation.
 
         :param inputs: A list of input mappings for each step;
-          its length is the number of steps to be executed.
+            its length is the number of steps to be executed.
         """
         steps = len(inputs)
         # create i/o arrays of the appropriate length
@@ -288,7 +288,7 @@ def run(self, inputs):
             self.tracer.trace[name].extend(res)
 
     def _traceable(self, wv):
-        """Check if wv is able to be traced
+        """ Check if wv is able to be traced.
 
         If it is traceable due to a probe, record that probe in _probe_mapping.
         """
@@ -301,7 +301,7 @@ def _traceable(self, wv):
         return False
 
     def _remove_untraceable(self):
-        """Remove from the tracer those wires that CompiledSimulation cannot track.
+        """ Remove from the tracer those wires that CompiledSimulation cannot track.
 
         Create _probe_mapping for wires only traceable via probes.
         """
@@ -312,7 +312,7 @@ def _remove_untraceable(self):
         self.tracer.trace.__init__(wvs)
 
     def _create_dll(self):
-        """Create a dynamically-linked library implementing the simulation logic."""
+        """ Create a dynamically-linked library implementing the simulation logic. """
         self._dir = tempfile.mkdtemp()
         with open(path.join(self._dir, 'pyrtlsim.c'), 'w') as f:
             self._create_code(lambda s: f.write(s + '\n'))
@@ -334,19 +334,19 @@ def _create_dll(self):
         self._mem_lookup.restype = ctypes.POINTER(ctypes.c_uint64)
 
     def _limbs(self, w):
-        """Number of 64-bit words needed to store value of wire."""
+        """ Number of 64-bit words needed to store value of wire. """
         return (w.bitwidth + 63) // 64
 
     def _makeini(self, w, v):
-        """C initializer string for a wire with a given value."""
+        """ C initializer string for a wire with a given value. """
         pieces = []
         for _ in range(self._limbs(w)):
             pieces.append(hex(v & ((1 << 64) - 1)))
             v >>= 64
         return ','.join(pieces).join('{}')
 
     def _romwidth(self, m):
-        """Bitwidth of integer type sufficient to hold rom entry.
+        """ Bitwidth of integer type sufficient to hold rom entry.
 
         On large memories, returns 64; an array will be needed.
         """
@@ -369,18 +369,18 @@ def _makemask(self, dest, res, pos):
         return ''
 
     def _getarglimb(self, arg, n):
-        """Get the nth limb of the given wire.
+        """ Get the nth limb of the given wire.
 
         Returns '0' when the wire does not have sufficient limbs.
         """
         return '{vn}[{n}]'.format(vn=self.varname[arg], n=n) if arg.bitwidth > 64 * n else '0'
 
     def _clean_name(self, prefix, obj):
-        """Create a C variable name with the given prefix based on the name of obj."""
+        """ Create a C variable name with the given prefix based on the name of obj. """
         return '{}{}_{}'.format(prefix, self._uid(), ''.join(c for c in obj.name if c.isalnum()))
 
     def _uid(self):
-        """Get an auto-incrementing number suitable for use as a unique identifier."""
+        """ Get an auto-incrementing number suitable for use as a unique identifier. """
         x = self._uid_counter
         self._uid_counter += 1
         return x

pyrtl/conditional.py

@@ -58,7 +58,7 @@
 
 
 def currently_under_condition():
-    """Returns True if execution is currently in the context of a _ConditionalAssignment."""
+    """ Returns True if execution is currently in the context of a _ConditionalAssignment. """
     return _depth > 0
 
 
@@ -67,7 +67,7 @@ def currently_under_condition():
 # instances (hopefully the only and unchanging instances) of the following two types.
 
 class _ConditionalAssignment(object):
-    """ helper type of global "conditional_assignment". """
+    """ Helper type of global "conditional_assignment". """
     def __enter__(self):
         global _depth
         _check_no_nesting()
@@ -83,7 +83,7 @@ def __exit__(self, *exc_info):
 
 
 class _Otherwise(object):
-    """ helper type of global "otherwise". """
+    """ Helper type of global "otherwise". """
     def __enter__(self):
         _push_condition(otherwise)
 
@@ -92,7 +92,7 @@ def __exit__(self, *exc_info):
 
 
 def _reset_conditional_state():
-    """Set or reset all the module state required for conditionals."""
+    """ Set or reset all the module state required for conditionals. """
     global _conditions_list_stack
     global _conflicts_map
     global _predicate_map

pyrtl/core.py

@@ -370,7 +370,8 @@ def wirevector_subset(self, cls=None, exclude=tuple()):
         If no cls is specified, the full set of wirevectors associated with the Block are
         returned.  If cls is a single type, or a tuple of types, only those wirevectors of
         the matching types will be returned.  This is helpful for getting all inputs, outputs,
-        or registers of a block for example."""
+        or registers of a block for example.
+        """
         if cls is None:
             initial_set = self.wirevector_set
         else:
@@ -384,7 +385,8 @@ def logic_subset(self, op=None):
         """Return set of logicnets, filtered by the type(s) of logic op provided as op.
 
         If no op is specified, the full set of logicnets associated with the Block are
-        returned.  This is helpful for getting all memories of a block for example."""
+        returned.  This is helpful for getting all memories of a block for example.
+        """
         if op is None:
             return self.logic
         else:
@@ -395,7 +397,8 @@ def get_wirevector_by_name(self, name, strict=False):
 
         By fallthrough, if a matching wirevector cannot be found the value None is
         returned.  However, if the argument strict is set to True, then this will
-        instead throw a PyrtlError when no match is found."""
+        instead throw a PyrtlError when no match is found.
+        """
         if name in self.wirevector_by_name:
             return self.wirevector_by_name[name]
         elif strict:
@@ -468,7 +471,8 @@ def __iter__(self):
         Note: this method will throw an error if there are loops in the
         logic that do not involve registers.
         Also, the order of the nets is not guaranteed to be the same
-        over multiple iterations"""
+        over multiple iterations.
+        """
         from .wire import Input, Const, Register
         src_dict, dest_dict = self.net_connections()
         to_clear = self.wirevector_subset((Input, Const, Register))
@@ -498,7 +502,8 @@ def sanity_check(self):
         """ Check block and throw PyrtlError or PyrtlInternalError if there is an issue.
 
         Should not modify anything, only check data structures to make sure they have been
-        built according to the assumptions stated in the Block comments."""
+        built according to the assumptions stated in the Block comments.
+        """
 
         # TODO: check that the wirevector_by_name is sane
         from .wire import Input, Const, Output
@@ -724,7 +729,7 @@ def sanity_check_net(self, net):
 
 class PostSynthBlock(Block):
     """ This is a block with extra metadata required to maintain the
-    pre synthesis interface post synthesis
+    pre-synthesis interface during post-synthesis.
     """
 
     def __init__(self):
@@ -758,7 +763,8 @@ def _get_debug_mode():
 
 
 def _get_useful_callpoint_name():
-    """ Attempts to find the lowest user-level call into the pyrtl module
+    """ Attempts to find the lowest user-level call into the PyRTL module.
+
     :return (string, int) or None: the file name and line number respectively
 
     This function walks back the current frame stack attempting to find the
@@ -815,10 +821,10 @@ def reset_working_block():
 
 class set_working_block(object):
     """ Set the working block to be the block passed as argument.
-        Compatible with the 'with' statement
+    Compatible with the 'with' statement.
 
-        Sanity checks will only be run if the new block is different
-        from the original block
+    Sanity checks will only be run if the new block is different
+    from the original block.
     """
 
     @staticmethod
@@ -844,8 +850,9 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 
 def temp_working_block():
     """ Set the working block to be new temporary block.
-        If used with the 'with' statement the block will be reset to the
-        original value (at the time of call) at exit of the context.
+
+    If used with the 'with' statement the block will be reset to the
+    original value (at the time of call) at exit of the context.
     """
     return set_working_block(Block())
 
@@ -864,13 +871,13 @@ def set_debug_mode(debug=True):
 
 
 class _NameIndexer(object):
-    """ Provides internal names that are based on a prefix and an index"""
+    """ Provides internal names that are based on a prefix and an index. """
     def __init__(self, internal_prefix='_sani_temp'):
         self.internal_prefix = internal_prefix
         self.internal_index = 0
 
     def make_valid_string(self):
-        """Build a valid string based on the prefix and internal index"""
+        """ Build a valid string based on the prefix and internal index. """
         return self.internal_prefix + str(self.next_index())
 
     def next_index(self):
@@ -880,9 +887,8 @@ def next_index(self):
 
 
 class _NameSanitizer(_NameIndexer):
-    """
-    Sanitizes the names so that names can be used in places that don't allow
-    for arbitrary names while not mangling valid names
+    """ Sanitizes the names so that names can be used in places that don't allow
+    for arbitrary names while not mangling valid names.
 
     Put the values you want to validate into make_valid_string the first time
     you want to sanitize a particular string (or before the first time), and
@@ -902,7 +908,7 @@ def __init__(self, identifier_regex_str, internal_prefix='_sani_temp',
         super(_NameSanitizer, self).__init__(internal_prefix)
 
     def __getitem__(self, item):
-        """ Get a value from the sanitizer"""
+        """ Get a value from the sanitizer """
         if not self.map_valid and self.is_valid_str(item):
             return item
         return self.val_map[item]
@@ -911,7 +917,7 @@ def is_valid_str(self, string):
         return self.identifier.match(string) and self.extra_checks(string)
 
     def make_valid_string(self, string=''):
-        """ Inputting a value for the first time """
+        """ Inputting a value for the first time. """
         if not self.is_valid_str(string):
             if string in self.val_map and not self.allow_dups:
                 raise IndexError("Value {} has already been given to the sanitizer".format(string))
@@ -925,7 +931,7 @@ def make_valid_string(self, string=''):
 
 
 class _PythonSanitizer(_NameSanitizer):
-    """ Name Sanitizer specifically built for Python identifers"""
+    """ Name Sanitizer specifically built for Python identifers. """
     def __init__(self, internal_prefix='_sani_temp', map_valid_vals=True):
         super(_PythonSanitizer, self).__init__(_py_regex, internal_prefix, map_valid_vals)
         self.extra_checks = lambda s: not keyword.iskeyword(s)