-

Ram Rachum · Ram Rachum · commit 6db973f03b68 · 2011-02-16T17:29:27.000+02:00
diff --git a/garlicsim/garlicsim/general_misc/arguments_profile.py b/garlicsim/garlicsim/general_misc/arguments_profile.py
@@ -422,7 +422,7 @@ def __getitem__(self, argument_name):
     
     def get(self, argument_name, default=None):
         '''Get the value of a specified argument, if missing get `default`.'''
-        return self._arguments.get(key, argument_name)
+        return self._arguments.get(argument_name, default)
     
     
     def keys(self):
diff --git a/garlicsim/garlicsim/general_misc/function_anchoring_type.py b/garlicsim/garlicsim/general_misc/function_anchoring_type.py
@@ -52,7 +52,7 @@ def __new__(mcls, name, bases, namespace_dict):
             
             # Since this metaclass is a hacky enough solution as it is, let's
             # be careful and ensure no object is already defined by the same
-            # name in the module level: (blocktodotest)
+            # name in the module level: (todotest)
             try:
                 already_defined_object = getattr(module_name, function_name)
             except AttributeError:
diff --git a/garlicsim/garlicsim/general_misc/import_tools.py b/garlicsim/garlicsim/general_misc/import_tools.py
@@ -118,22 +118,29 @@ def import_if_exists(module_name, silent_fail=False):
 
 
 def _module_exists_in_some_zip_path(module_name):
+    '''
+    Return whether a module by the name `module_name` exists in a zip archive.
+    
+    Used internally by `exists`.
+    '''
     assert '.' not in module_name
     
     zip_paths = [path for path in sys.path if '.zip' in path]
     # todo: Find better way to filter zip paths.
     
     for zip_path in zip_paths:
 
-        # Trying to create a zip imported:
+        # Trying to create a zip importer:
         try:
             zip_importer = zipimport.zipimporter(zip_path)
         except zipimport.ZipImportError:
             continue
             # Excepted `ZipImportError` because we may have zip paths in
             # `sys.path` that don't really exist, which causes `zipimport` to
-            # raise `ZipImportError`. todo: should find smarter way of catching
-            # this, excepting `ZipImportError` is not a good idea.
+            # raise `ZipImportError`.
+            #
+            # todo: should find smarter way of catching this, excepting
+            # `ZipImportError` is not a good idea.
         
         if zip_importer.find_module(module_name) is not None:    
             return True
@@ -151,7 +158,7 @@ def exists(module_name):
     
     Currently implemented for top-level packages only. (i.e. no dots.)
     
-    (Supports modules imported from a zip file.)
+    Supports modules imported from a zip file.
     '''
     assert '.' not in module_name
     try:
diff --git a/garlicsim/garlicsim/general_misc/misc_tools.py b/garlicsim/garlicsim/general_misc/misc_tools.py
@@ -17,9 +17,17 @@ def is_subclass(candidate, base_class):
     You may pass in a tuple of base classes instead of just one, and it will
     check whether `candidate` is a subclass of any of these base classes.
     
-    tododoc The advantage of this over the built-in `issubclass` is that it doesn't
-    throw an exception if `candidate` is not a type. (Python issue 10569.)
+    This has 2 advantages of over the built-in `issubclass`:
+    
+     1. It doesn't throw an exception if `candidate` is not a type. (Python
+        issue 10569.)
+     2. It manually checks for a `__subclasscheck__` method on `base_class`.
+        This is helpful for Python 2.5 compatibility because Python started
+        using `__subclasscheck__` in its built-in `issubclass` starting from
+        Python 2.6.
+        
     '''
+    # todo: disable ability to use nested iterables.
     if cute_iter_tools.is_iterable(base_class):
         return any(is_subclass(candidate, single_base_class) for 
                    single_base_class in base_class)
diff --git a/garlicsim/garlicsim/general_misc/sequence_tools.py b/garlicsim/garlicsim/general_misc/sequence_tools.py
@@ -37,8 +37,8 @@ def combinations(sequence, n=None, start=0):
 
     `n` specifies the number of items. (Use `None` for all possible sizes
     together.) `start` specifies the index number of the member from which to
-    start giving combinations. (Keep the default of `0` for doing the whole
-    sequence.)
+    start giving combinations. (Keep the default of `start=0` for doing the
+    whole sequence.)
     
     Example:
     
@@ -63,7 +63,6 @@ def combinations(sequence, n=None, start=0):
                 yield [thing] + sub_result
 
 
-
 ### Not using now, might want in future:
 
 #def is_sequence(thing):
diff --git a/garlicsim/garlicsim/general_misc/sys_tools.py b/garlicsim/garlicsim/general_misc/sys_tools.py
@@ -84,6 +84,11 @@ def __exit__(self, *args, **kwargs):
 
             
 frozen = getattr(sys, 'frozen', None)
+'''
+The "frozen string", if we are frozen, otherwise `None`.
+
+This is useful for checking if we are frozen, e.g. with py2exe.
+'''
 
 
 # May want in future:
diff --git a/garlicsim/garlicsim/misc/caching/__init__.py b/garlicsim/garlicsim/misc/caching/__init__.py
@@ -1,6 +1,7 @@
 # Copyright 2009-2011 Ram Rachum.
 # This program is distributed under the LGPL2.1 license.
 
-'''Package for caching of functions that take states or history browsers.'''
+'''Package for caching of functions that take history browsers.'''
+# todo: reorganize?
 
 from .decorators import history_cache
diff --git a/garlicsim/garlicsim/misc/caching/decorators.py b/garlicsim/garlicsim/misc/caching/decorators.py
@@ -2,12 +2,12 @@
 # This program is distributed under the LGPL2.1 license.
 
 '''
-tododoc perhaps reorganize
-Provides decorators to cache state- or history-dependent functions.
+This module defines the `history_cache` decorator.
 
-`state_cache` is for functions that take a state. `history_cache` is for
-functions that take a history browser.
+See its documentation for more information.
 '''
+
+# todo perhaps reorganize
 #todo: make sure the cache gets lost on pickling
 
 from __future__ import with_statement
diff --git a/garlicsim/garlicsim/misc/simpack_grokker/settings.py b/garlicsim/garlicsim/misc/simpack_grokker/settings.py
@@ -52,7 +52,8 @@ def __init__(self, simpack_grokker):
         List of scalar state functions given by the simpack.
         
         A scalar state function is a function from a state to a real number.
-        These should be decorated by `garlicsim.misc.cached.state_cache`. tododoc
+        It's recommended to decorate these with
+        `garlicsim.general_misc.caching.cache`
         '''
         
         self.SCALAR_HISTORY_FUNCTIONS = []
diff --git a/garlicsim/garlicsim/scripts/start_simpack.py b/garlicsim/garlicsim/scripts/start_simpack.py
@@ -5,8 +5,16 @@
 '''
 Script for starting a new simpack.
 
+This is a script for creating a skeleton for a `garlicsim` simpack. Use this
+when you want to make a new simpack to have the basic folders and files created
+for you.
+
 Usage:
-start_simpack.py quantum_mechanics
+
+    start_simpack.py my_simpack_name
+
+The simpack will be created in the current path, in a directory with the name
+of the simpack.
 '''
 
 from __future__ import with_statement
@@ -21,18 +29,6 @@
 from garlicsim.scripts import simpack_template
 simpack_template_package_name = simpack_template.__name__
 
-
-_help_text =  '''\
-This is a script for creating a skeleton for a `garlicsim` simpack. Use this
-when you want to make a new simpack to have the basic folders and files created
-for you.
-
-    Usage: start_simpack.py my_simpack_name
-
-The simpack will be created in the current path, in a directory with the name
-of the simpack.
-'''
-
     
 def _walk_folder(package_name, folder):
     '''
@@ -113,7 +109,6 @@ def start_simpack(containing_folder, name):
             string_to_write = source_string\
                             .replace('\r', '')\
                             .replace('simpack_name', name)
-                            
             
             destination.write(string_to_write)
             
@@ -141,8 +136,8 @@ def _make_writeable(filename):
 
         
 def show_help():
-    '''Print some help text that describes how to use this script'''
-    print(_help_text)
+    '''Print some help text that describes how to use this script.'''
+    print(__doc__)
 
  
 def start(argv=None):
diff --git a/garlicsim/test_garlicsim/test_scripts/test_start_simpack.py b/garlicsim/test_garlicsim/test_scripts/test_start_simpack.py
@@ -14,12 +14,16 @@
 import garlicsim.scripts
 
 
-_help_text = '''\
+_help_text = '''
+Script for starting a new simpack.
+
 This is a script for creating a skeleton for a `garlicsim` simpack. Use this
 when you want to make a new simpack to have the basic folders and files created
 for you.
 
-    Usage: start_simpack.py my_simpack_name
+Usage:
+
+    start_simpack.py my_simpack_name
 
 The simpack will be created in the current path, in a directory with the name
 of the simpack.
