update/fix documentation

README.rst

@@ -21,7 +21,27 @@ Akamai SecureHD Token Authorization VMOD
 SYNOPSIS
 ========
 
-import hoailona [from "path"] ;
+
+::
+
+   import hoailona [from "path"] ;
+   
+   new xpolicy = hoailona.policy(ENUM type, DURATION ttl, STRING description, BLOB secret, INT start_offset)
+  
+   new xhosts = hoailona.hosts()
+  
+      VOID xhosts.add(STRING host, STRING policy, STRING path, STRING description)
+  
+      INT xhosts.policy(STRING host, STRING path)
+  
+      STRING xhosts.token(STRING acl, DURATION ttl, STRING data)
+  
+      BLOB xhosts.secret()
+  
+      STRING xhosts.explain()
+  
+   STRING version()
+  
 
 
 ::
@@ -73,7 +93,7 @@ does provide the means to associate shared secrets with a policy,
 which can be used together with a VMOD that does compute HMACs (such
 as the ``blobdigest`` VMOD, see `SEE ALSO`_).
 
-The name of the VMOD is inspired by the Hawaiian word *hō`ailona*, for
+The name of the VMOD is inspired by the Hawaiian word *ho`ailona*, for
 "sign" or "symbol" (pronounced "ho-eye-lona"), which we believe to be
 a suitable translation for "token". We welcome feedback from speakers
 of Hawaiian about the choice of the name.
@@ -226,21 +246,21 @@ subroutines, subsequent calls to ``.token()`` and ``.secret()`` in the
 same backend transaction are based on the policy that was determined
 by that call.
 
-CONTENTS
-========
-
-* policy(ENUM {OPEN,DENY,TOKEN}, DURATION, STRING, BLOB, INT)
-* hosts()
-* STRING version()
 
 .. _obj_policy:
 
-policy
-------
+policy(...)
+-----------
 
 ::
 
-	new OBJ = policy(ENUM {OPEN,DENY,TOKEN} type, DURATION ttl=0, STRING description=0, BLOB secret=0, INT start_offset=0)
+   new xpolicy = hoailona.policy(
+      ENUM {OPEN, DENY, TOKEN} type,
+      DURATION ttl=0,
+      STRING description=0,
+      BLOB secret=0,
+      INT start_offset=0
+   )
 
 Create a policy. The ``type`` enum is required, to classify the policy
 as ``OPEN``, ``DENY`` or ``TOKEN``.
@@ -295,14 +315,13 @@ Examples::
   # A policy for "access denied"
   new forbid = hoailona.policy(DENY, description="access denied");
 
-.. _obj_hosts:
 
-hosts
------
 
-::
 
-	new OBJ = hosts()
+.. _obj_hosts:
+
+new xhosts = hoailona.hosts()
+-----------------------------
 
 Create a ``hosts`` object, which provides a store for a configuration
 that associates with policies with hostnames, and optionally with
@@ -311,12 +330,17 @@ becomes useful by calling the ``.add()`` method.
 
 .. _func_hosts.add:
 
-hosts.add
----------
+hosts.add(...)
+--------------
 
 ::
 
-	VOID hosts.add(STRING host, STRING policy, STRING path=0, STRING description=0)
+      VOID xhosts.add(
+            STRING host,
+            STRING policy,
+            STRING path=0,
+            STRING description=0
+      )
 
 Associate ``policy`` with the ``host``, optionally restricted to the
 path pattern described by ``path``. The ``host`` and ``policy``
@@ -449,14 +473,11 @@ Examples::
     h.add("evil.org", "deny", description="no access to evil.org");
   }
 
-.. _func_hosts.policy:
-
-hosts.policy
-------------
 
-::
+.. _func_hosts.policy:
 
-	INT hosts.policy(STRING host=0, STRING path=0)
+INT xhosts.policy(STRING host=0, STRING path=0)
+-----------------------------------------------
 
 Determine the policy type that holds for ``host`` and ``path``. The
 return values are:
@@ -520,14 +541,19 @@ with parameters.
 Calling ``.policy()`` with only one of the ``host`` and ``path``
 parameters empty is an error.
 
+
 .. _func_hosts.token:
 
-hosts.token
------------
+STRING xhosts.token(STRING acl, DURATION ttl, STRING data)
+----------------------------------------------------------
 
 ::
 
-	STRING hosts.token(STRING acl=0, DURATION ttl=0, STRING data=0)
+      STRING xhosts.token(
+            STRING acl=0,
+            DURATION ttl=0,
+            STRING data=0
+      )
 
 If the previous invocation of ``.policy()`` determined policy type
 ``TOKEN`` (return value 2 from ``.policy()``), then return the
@@ -577,14 +603,11 @@ Examples::
       # needed for SecureHD authorization.
   }
 
-.. _func_hosts.secret:
 
-hosts.secret
-------------
-
-::
+.. _func_hosts.secret:
 
-	BLOB hosts.secret()
+BLOB xhosts.secret()
+--------------------
 
 Return the shared secret stored for the policy determined by the
 previous invocation of ``.policy()``. Returns NULL if no such shared
@@ -624,14 +647,11 @@ Examples::
     }
   }
 
-.. _func_hosts.explain:
 
-hosts.explain
--------------
-
-::
+.. _func_hosts.explain:
 
-	STRING hosts.explain()
+STRING xhosts.explain()
+-----------------------
 
 Returns a string describing the policy that was determined for a host
 and path by the most recent invocation of ``.policy()`` in the current
@@ -662,14 +682,14 @@ Example::
     std.log("Policy determination: " + config.explain());
   }
 
-.. _func_version:
 
-version
--------
 
-::
 
-	STRING version()
+
+.. _func_version:
+
+STRING version()
+----------------
 
 Returns the version string for this VMOD.
 
@@ -748,6 +768,7 @@ Users of the Luna Control Center can consult:
 
   * https://control.akamai.com/dl/customers/SPE/EdgeAuth-latest.zip
 
+
 COPYRIGHT
 =========