changeset 736:0f6bc89072ae

Added viff.util to documentation.
author Martin Geisler <mg@daimi.au.dk>
date Fri, 25 Apr 2008 08:25:28 +0200
parents f51415df0335
children 75f932a949eb
files doc/implementation.txt doc/util.txt viff/util.py
diffstat 3 files changed, 24 insertions(+), 16 deletions(-) [+]
line wrap: on
line diff
--- a/doc/implementation.txt	Fri Apr 25 08:24:12 2008 +0200
+++ b/doc/implementation.txt	Fri Apr 25 08:25:28 2008 +0200
@@ -7,6 +7,7 @@
 .. toctree::
    :maxdepth: 2
 
+   util
    field
    shamir
    matrix
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/util.txt	Fri Apr 25 08:25:28 2008 +0200
@@ -0,0 +1,6 @@
+
+Utility Functions Module
+========================
+
+.. automodule:: viff.util
+   :members:
--- a/viff/util.py	Fri Apr 25 08:24:12 2008 +0200
+++ b/viff/util.py	Fri Apr 25 08:25:28 2008 +0200
@@ -18,19 +18,21 @@
 """Miscellaneous utility functions.
 
 This module contains various utility functions used in all parts of
-the VIFF code. The most important is the L{rand} random generator
+the VIFF code. The most important is the :data:`rand` random generator
 which is seeded with a known seed each time. Using this generator for
 all random numbers ensures that a protocol run can be reproduced at a
 later time.
 """
 
+__docformat__ = "restructuredtext"
+
 import os
 import random
 import warnings
 from twisted.internet.defer import Deferred, succeed, gatherResults
 from gmpy import mpz
 
-#: Seed for L{rand}.
+#: Seed for :data:`rand`.
 _seed = os.environ.get('SEED')
 
 if _seed is None:
@@ -41,8 +43,8 @@
     #: Random number generator used by all VIFF code.
     #:
     #: The generator is by default initialized with a random seed,
-    #: unless the environment variable C{SEED} is set to a value, in
-    #: which case that value is used instead. If C{SEED} is defined,
+    #: unless the environment variable :envvar:`SEED` is set to a value, in
+    #: which case that value is used instead. If :envvar:`SEED` is defined,
     #: but empty, then no seed is used and a protocol cannot be
     #: reproduced exactly.
     rand = random.Random(_seed)
@@ -61,19 +63,17 @@
     """Decorator used for wrapper functions.
 
     It is important to use this decorator on any wrapper functions in
-    order to ensure that they end up with correct C{__name__} and
-    C{__doc__} attributes.
+    order to ensure that they end up with correct :attr:`__name__` and
+    :attr:`__doc__` attributes.
 
-    In addition, if the environment variable C{VIFF_NO_WRAP} is
+    In addition, if the environment variable :envvar:`VIFF_NO_WRAP` is
     defined, then the wrapper functions will be turned into functions
-    that I{do not} wrap -- instead they let their argument function
+    that *do not* wrap -- instead they let their argument function
     through unchanged. This is done so that epydoc and Sphinx can see
     the true function arguments when generating documentation. Just
-    remember that your code will break if C{VIFF_NO_WRAP} is set, so
-    it should only be used when documentation is being generated.
-
-    @param func: the function that will be wrapped.
-    @type func: callable
+    remember that your code will break if :envvar:`VIFF_NO_WRAP` is
+    set, so it should only be used when documentation is being
+    generated.
     """
     if os.environ.get('VIFF_NO_WRAP'):
         # Return a decorator which ignores the functions it is asked
@@ -168,10 +168,11 @@
     """Clone a Deferred.
 
     The returned clone will fire with the same result as the original
-    Deferred, but will otherwise be independent.
+    :class:`Deferred`, but will otherwise be independent.
 
-    It is an error to call callback on the clone as it will result in
-    an AlreadyCalledError when the original Deferred is triggered.
+    It is an error to call :meth:`callback` on the clone as it will
+    result in an :exc:`AlreadyCalledError` when the original
+    :class:`Deferred` is triggered.
 
     >>> x = Deferred()
     >>> x.addCallback(lambda result: result * 10) # doctest: +ELLIPSIS