[project @ Docblock additions and fixes ]

11 files changed, 311 insertions, 55 deletions

diff --git a/Auth/OpenID/Association.php b/Auth/OpenID/Association.php
index 3be5d53..16c83bf 100644
--- a/Auth/OpenID/Association.php
+++ b/Auth/OpenID/Association.php
@@ -315,6 +315,8 @@ class Auth_OpenID_Association {
      * Given a {@link Auth_OpenID_Message}, return the key/value pairs
      * to be signed according to the signed list in the message.  If
      * the message lacks a signed list, return null.
+     *
+     * @access private
      */
     function _makePairs(&$message)
     {
@@ -472,14 +474,59 @@ function &Auth_OpenID_getEncryptedNegotiator()
     return $x;
 }
 
+/**
+ * A session negotiator controls the allowed and preferred association
+ * types and association session types. Both the {@link
+ * Auth_OpenID_Consumer} and {@link Auth_OpenID_Server} use
+ * negotiators when creating associations.
+ *
+ * You can create and use negotiators if you:
+
+ * - Do not want to do Diffie-Hellman key exchange because you use
+ * transport-layer encryption (e.g. SSL)
+ *
+ * - Want to use only SHA-256 associations
+ *
+ * - Do not want to support plain-text associations over a non-secure
+ * channel
+ *
+ * It is up to you to set a policy for what kinds of associations to
+ * accept. By default, the library will make any kind of association
+ * that is allowed in the OpenID 2.0 specification.
+ *
+ * Use of negotiators in the library
+ * =================================
+ *
+ * When a consumer makes an association request, it calls {@link
+ * getAllowedType} to get the preferred association type and
+ * association session type.
+ *
+ * The server gets a request for a particular association/session type
+ * and calls {@link isAllowed} to determine if it should create an
+ * association. If it is supported, negotiation is complete. If it is
+ * not, the server calls {@link getAllowedType} to get an allowed
+ * association type to return to the consumer.
+ *
+ * If the consumer gets an error response indicating that the
+ * requested association/session type is not supported by the server
+ * that contains an assocation/session type to try, it calls {@link
+ * isAllowed} to determine if it should try again with the given
+ * combination of association/session type.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_SessionNegotiator {
     function Auth_OpenID_SessionNegotiator($allowed_types)
     {
         $this->allowed_types = $allowed_types;
     }
 
-    // Set the allowed association types, checking to make sure each
-    // combination is valid.
+    /**
+     * Set the allowed association types, checking to make sure each
+     * combination is valid.
+     *
+     * @access private
+     */
     function setAllowedTypes($allowed_types)
     {
         foreach ($allowed_types as $pair) {
@@ -493,9 +540,13 @@ class Auth_OpenID_SessionNegotiator {
         return true;
     }
 
-    // Add an association type and session type to the allowed types
-    // list. The assocation/session pairs are tried in the order that
-    // they are added.
+    /**
+     * Add an association type and session type to the allowed types
+     * list. The assocation/session pairs are tried in the order that
+     * they are added.
+     *
+     * @access private
+     */
     function addAllowedType($assoc_type, $session_type = null)
     {
         if ($this->allowed_types === null) {
@@ -535,8 +586,10 @@ class Auth_OpenID_SessionNegotiator {
         return ($assoc_good && $matches);
     }
 
-    // Get a pair of assocation type and session type that are
-    // supported
+    /**
+     * Get a pair of assocation type and session type that are
+     * supported.
+     */
     function getAllowedType()
     {
         if (!$this->allowed_types) {
diff --git a/Auth/OpenID/Consumer.php b/Auth/OpenID/Consumer.php
index 8e47ef1..3746b3f 100644
--- a/Auth/OpenID/Consumer.php
+++ b/Auth/OpenID/Consumer.php
@@ -256,6 +256,10 @@ class Auth_OpenID_Consumer {
      * which wraps PHP's native session machinery.  You should only
      * need to pass something here if you have your own sessioning
      * implementation.
+     *
+     * @param str consumer_cls The name of the class to instantiate
+     * when creating the internal consumer object.  This is used for
+     * testing.
      */
     function Auth_OpenID_Consumer(&$store, $session = null,
                                   $consumer_cls = null)
@@ -275,6 +279,11 @@ class Auth_OpenID_Consumer {
         $this->_token_key = $this->session_key_prefix . $this->_token_suffix;
     }
 
+    /**
+     * Used in testing to define the discovery mechanism.
+     *
+     * @access private
+     */
     function getDiscoveryObject(&$session, $openid_url,
                                 $session_key_prefix)
     {
@@ -292,6 +301,11 @@ class Auth_OpenID_Consumer {
      * will be normalized to http://example.com/ normalizing and
      * resolving any redirects the server might issue.
      *
+     * @param bool anonymous True if the OpenID request is to be sent
+     * to the server without any identifier information.  Use this
+     * when you want to transport data but don't want to do OpenID
+     * authentication with identifiers.
+     *
      * @return Auth_OpenID_AuthRequest $auth_request An object
      * containing the discovered information will be returned, with a
      * method for building a redirect URL to the server, as described
@@ -353,6 +367,9 @@ class Auth_OpenID_Consumer {
      * @param Auth_OpenID_ServiceEndpoint $endpoint an OpenID service
      * endpoint descriptor.
      *
+     * @param bool anonymous Set to true if you want to perform OpenID
+     * without identifiers.
+     *
      * @return Auth_OpenID_AuthRequest $auth_request An OpenID
      * authentication request object.
      */
@@ -372,7 +389,10 @@ class Auth_OpenID_Consumer {
      * consumer overview.
      *
      * @param array $query An array of the query parameters (key =>
-     * value pairs) for this HTTP request.
+     * value pairs) for this HTTP request.  Defaults to null.  If
+     * null, the GET or POST data are automatically gotten from the
+     * PHP environment.  It is only useful to override $query for
+     * testing.
      *
      * @return Auth_OpenID_ConsumerResponse $response A instance of an
      * Auth_OpenID_ConsumerResponse subclass. The type of response is
@@ -413,6 +433,11 @@ class Auth_OpenID_Consumer {
     }
 }
 
+/**
+ * A class implementing HMAC/DH-SHA1 consumer sessions.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_DiffieHellmanSHA1ConsumerSession {
     var $session_type = 'DH-SHA1';
     var $hash_func = 'Auth_OpenID_SHA1';
@@ -470,6 +495,11 @@ class Auth_OpenID_DiffieHellmanSHA1ConsumerSession {
     }
 }
 
+/**
+ * A class implementing HMAC/DH-SHA256 consumer sessions.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_DiffieHellmanSHA256ConsumerSession extends
       Auth_OpenID_DiffieHellmanSHA1ConsumerSession {
     var $session_type = 'DH-SHA256';
@@ -478,6 +508,11 @@ class Auth_OpenID_DiffieHellmanSHA256ConsumerSession extends
     var $allowed_assoc_types = array('HMAC-SHA256');
 }
 
+/**
+ * A class implementing plaintext consumer sessions.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_PlainTextConsumerSession {
     var $session_type = 'no-encryption';
     var $allowed_assoc_types =  array('HMAC-SHA1');
@@ -498,6 +533,9 @@ class Auth_OpenID_PlainTextConsumerSession {
     }
 }
 
+/**
+ * Returns available session types.
+ */
 function Auth_OpenID_getAvailableSessionTypes()
 {
     $types = array(
@@ -514,7 +552,6 @@ function Auth_OpenID_getAvailableSessionTypes()
  * reused (or even used by multiple threads concurrently) as needed.
  *
  * @package OpenID
- * @access private
  */
 class Auth_OpenID_GenericConsumer {
     /**
@@ -566,6 +603,12 @@ class Auth_OpenID_GenericConsumer {
         $this->session_types = Auth_OpenID_getAvailableSessionTypes();
     }
 
+    /**
+     * Called to begin OpenID authentication using the specified
+     * {@link Auth_OpenID_ServiceEndpoint}.
+     *
+     * @access private
+     */
     function begin($service_endpoint)
     {
         $assoc = $this->_getAssociation($service_endpoint);
@@ -575,6 +618,13 @@ class Auth_OpenID_GenericConsumer {
         return $r;
     }
 
+    /**
+     * Given an {@link Auth_OpenID_Message}, {@link
+     * Auth_OpenID_ServiceEndpoint} and optional return_to URL,
+     * complete OpenID authentication.
+     *
+     * @access private
+     */
     function complete($message, $endpoint, $return_to = null)
     {
         $mode = $message->getArg(Auth_OpenID_OPENID_NS, 'mode',
@@ -613,6 +663,9 @@ class Auth_OpenID_GenericConsumer {
         }
     }
 
+    /**
+     * @access private
+     */
     function _checkSetupNeeded($message)
     {
         // In OpenID 1, we check to see if this is a cancel from
@@ -684,6 +737,9 @@ class Auth_OpenID_GenericConsumer {
 
     }
 
+    /**
+     * @access private
+     */
     function _checkReturnTo($message, $return_to)
     {
         // Check an OpenID message and its openid.return_to value
@@ -744,6 +800,9 @@ class Auth_OpenID_GenericConsumer {
         return true;
     }
 
+    /**
+     * @access private
+     */
     function _verifyReturnToArgs($query)
     {
         // Verify that the arguments in the return_to URL are present in this
@@ -784,6 +843,9 @@ class Auth_OpenID_GenericConsumer {
         return true;
     }
 
+    /**
+     * @access private
+     */
     function _idResCheckSignature($message, $server_url)
     {
         $assoc_handle = $message->getArg(Auth_OpenID_OPENID_NS,
@@ -821,6 +883,9 @@ class Auth_OpenID_GenericConsumer {
         return null;
     }
 
+    /**
+     * @access private
+     */
     function _verifyDiscoveryResults($message, $endpoint=null)
     {
         if ($message->getOpenIDNamespace() == Auth_OpenID_OPENID2_NS) {
@@ -832,6 +897,9 @@ class Auth_OpenID_GenericConsumer {
         }
     }
 
+    /**
+     * @access private
+     */
     function _verifyDiscoveryResultsOpenID1($message, $endpoint)
     {
         if ($endpoint === null) {
@@ -871,6 +939,9 @@ class Auth_OpenID_GenericConsumer {
         }
     }
 
+    /**
+     * @access private
+     */
     function _verifyDiscoverySingle($endpoint, $to_match)
     {
         // Every type URI that's in the to_match endpoint has to be
@@ -914,6 +985,9 @@ class Auth_OpenID_GenericConsumer {
         return null;
     }
 
+    /**
+     * @access private
+     */
     function _verifyDiscoveryResultsOpenID2($message, $endpoint)
     {
         $to_match = new Auth_OpenID_ServiceEndpoint();
@@ -976,6 +1050,9 @@ class Auth_OpenID_GenericConsumer {
         // Never reached.
     }
 
+    /**
+     * @access private
+     */
     function _discoverAndVerify($to_match)
     {
         // oidutil.log('Performing discovery on %s' % (to_match.claimed_id,))
@@ -1009,6 +1086,9 @@ class Auth_OpenID_GenericConsumer {
                   $to_match->claimed_id));
     }
 
+    /**
+     * @access private
+     */
     function _idResGetNonceOpenID1($message, $endpoint)
     {
         $return_to = $message->getArg(Auth_OpenID_OPENID1_NS,
@@ -1039,6 +1119,9 @@ class Auth_OpenID_GenericConsumer {
         return null;
     }
 
+    /**
+     * @access private
+     */
     function _idResCheckNonce($message, $endpoint)
     {
         if ($message->isOpenID1()) {
@@ -1074,6 +1157,9 @@ class Auth_OpenID_GenericConsumer {
         return null;
     }
 
+    /**
+     * @access private
+     */
     function _idResCheckForFields($message, $signed_list)
     {
         $basic_fields = array('return_to', 'assoc_handle', 'sig');
@@ -1252,6 +1338,9 @@ class Auth_OpenID_GenericConsumer {
         return $assoc;
     }
 
+    /**
+     * @access private
+     */
     function _negotiateAssociation($endpoint)
     {
         // Get our preferred session/association type from the negotiatior.
@@ -1326,6 +1415,9 @@ class Auth_OpenID_GenericConsumer {
         return $assoc;
     }
 
+    /**
+     * @access private
+     */
     function _requestAssociation($endpoint, $assoc_type, $session_type)
     {
         list($assoc_session, $args) = $this->_createAssociateRequest(
@@ -1344,6 +1436,9 @@ class Auth_OpenID_GenericConsumer {
         return $this->_extractAssociation($response_message, $assoc_session);
     }
 
+    /**
+     * @access private
+     */
     function _extractAssociation(&$assoc_response, &$assoc_session)
     {
         // Extract the common fields from the response, raising an
@@ -1434,6 +1529,9 @@ class Auth_OpenID_GenericConsumer {
                  $expires_in, $assoc_handle, $secret, $assoc_type);
     }
 
+    /**
+     * @access private
+     */
     function _createAssociateRequest($endpoint, $assoc_type, $session_type)
     {
         if (array_key_exists($session_type, $this->session_types)) {
@@ -1463,19 +1561,19 @@ class Auth_OpenID_GenericConsumer {
         return array($assoc_session, $message);
     }
 
-    // Given an association response message, extract the OpenID 1.X
-    // session type.
-    //
-    // This function mostly takes care of the 'no-encryption' default
-    // behavior in OpenID 1.
-    //
-    // If the association type is plain-text, this function will
-    // return 'no-encryption'
-    //
-    // @returns: The association type for this message
-    // @rtype: str
-    // 
-    // @raises: KeyError, if the session_type field is absent.
+    /**
+     * Given an association response message, extract the OpenID 1.X
+     * session type.
+     *
+     * This function mostly takes care of the 'no-encryption' default
+     * behavior in OpenID 1.
+     *
+     * If the association type is plain-text, this function will
+     * return 'no-encryption'
+     *
+     * @access private
+     * @return $typ The association type for this message
+     */
     function _getOpenID1SessionType($assoc_response)
     {
         // If it's an OpenID 1 message, allow session_type to default
@@ -1852,6 +1950,8 @@ class Auth_OpenID_FailureResponse extends Auth_OpenID_ConsumerResponse {
 
 /**
  * A specific, internal failure used to detect type URI mismatch.
+ *
+ * @package OpenID
  */
 class Auth_OpenID_TypeURIMismatch extends Auth_OpenID_FailureResponse {
 }
@@ -1859,6 +1959,8 @@ class Auth_OpenID_TypeURIMismatch extends Auth_OpenID_FailureResponse {
 /**
  * Exception that is raised when the server returns a 400 response
  * code to a direct request.
+ *
+ * @package OpenID
  */
 class Auth_OpenID_ServerErrorContainer {
     function Auth_OpenID_ServerErrorContainer($error_text,
@@ -1870,6 +1972,9 @@ class Auth_OpenID_ServerErrorContainer {
         $this->message = $message;
     }
 
+    /**
+     * @access private
+     */
     function fromMessage($message)
     {
         $error_text = $message->getArg(
diff --git a/Auth/OpenID/Extension.php b/Auth/OpenID/Extension.php
index 6f943c2..73b5d50 100644
--- a/Auth/OpenID/Extension.php
+++ b/Auth/OpenID/Extension.php
@@ -2,10 +2,21 @@
 
 /**
  * An interface for OpenID extensions.
+ *
+ * @package OpenID
  */
 
+/**
+ * Require the Message implementation.
+ */
 require_once 'Auth/OpenID/Message.php';
 
+/**
+ * A base class for accessing extension request and response data for
+ * the OpenID 2 protocol.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_Extension {
     /**
      * ns_uri: The namespace to which to add the arguments for this
diff --git a/Auth/OpenID/FileStore.php b/Auth/OpenID/FileStore.php
index 9639611..acf0dd2 100644
--- a/Auth/OpenID/FileStore.php
+++ b/Auth/OpenID/FileStore.php
@@ -12,7 +12,6 @@
  * @author JanRain, Inc. <openid@janrain.com>
  * @copyright 2005 Janrain, Inc.
  * @license http://www.gnu.org/copyleft/lesser.html LGPL
- *
  */
 
 /**
@@ -372,6 +371,8 @@ class Auth_OpenID_FileStore extends Auth_OpenID_OpenIDStore {
     /**
      * Remove expired entries from the database. This is potentially
      * expensive, so only run when it is acceptable to take time.
+     *
+     * @access private
      */
     function _allAssocs()
     {
diff --git a/Auth/OpenID/Message.php b/Auth/OpenID/Message.php
index cdc4d65..53a3602 100644
--- a/Auth/OpenID/Message.php
+++ b/Auth/OpenID/Message.php
@@ -2,10 +2,13 @@
 
 /**
  * Extension argument processing code
+ *
+ * @package OpenID
  */
 
-// import urllib
-
+/**
+ * Import tools needed to deal with messages.
+ */
 require_once 'Auth/OpenID.php';
 require_once 'Auth/OpenID/KVForm.php';
 require_once 'Auth/Yadis/XML.php';
@@ -104,6 +107,8 @@ function Auth_OpenID_removeNamespaceAlias($namespace_uri, $alias)
  * An Auth_OpenID_Mapping maintains a mapping from arbitrary keys to
  * arbitrary values.  (This is unlike an ordinary PHP array, whose
  * keys may be only simple scalars.)
+ *
+ * @package OpenID
  */
 class Auth_OpenID_Mapping {
     /**
@@ -202,6 +207,9 @@ class Auth_OpenID_Mapping {
         }
     }
 
+    /**
+     * @access private
+     */
     function _reflow()
     {
         // PHP is broken yet again.  Sort the arrays to remove the
@@ -250,6 +258,8 @@ class Auth_OpenID_Mapping {
 
 /**
  * Maintains a bijective map between namespace uris and aliases.
+ *
+ * @package OpenID
  */
 class Auth_OpenID_NamespaceMap {
     function Auth_OpenID_NamespaceMap()
@@ -376,6 +386,8 @@ class Auth_OpenID_NamespaceMap {
 /**
  * In the implementation of this object, null represents the global
  * namespace as well as a namespace with no key.
+ *
+ * @package OpenID
  */
 class Auth_OpenID_Message {
 
@@ -453,6 +465,9 @@ class Auth_OpenID_Message {
         }
     }
 
+    /**
+     * @access private
+     */
     function _fromOpenIDArgs($openid_args)
     {
         global $Auth_OpenID_registered_aliases;
@@ -688,6 +703,9 @@ class Auth_OpenID_Message {
         return Auth_OpenID::httpBuildQuery($args);
     }
 
+    /**
+     * @access private
+     */
     function _fixNS($namespace)
     {
         // Convert an input value into the internally used values of
diff --git a/Auth/OpenID/Nonce.php b/Auth/OpenID/Nonce.php
index 7107097..71a33e1 100644
--- a/Auth/OpenID/Nonce.php
+++ b/Auth/OpenID/Nonce.php
@@ -2,8 +2,13 @@
 
 /**
  * Nonce-related functionality.
+ *
+ * @package OpenID
  */
 
+/**
+ * Need CryptUtil to generate random strings.
+ */
 require_once 'Auth/OpenID/CryptUtil.php';
 
 /**
diff --git a/Auth/OpenID/SQLiteStore.php b/Auth/OpenID/SQLiteStore.php
index 95c4d1d..debb5fe 100644
--- a/Auth/OpenID/SQLiteStore.php
+++ b/Auth/OpenID/SQLiteStore.php
@@ -49,6 +49,9 @@ class Auth_OpenID_SQLiteStore extends Auth_OpenID_SQLStore {
             "INSERT INTO %s (server_url, timestamp, salt) VALUES (?, ?, ?)";
     }
 
+    /**
+     * @access private
+     */
     function _add_nonce($server_url, $timestamp, $salt)
     {
         // PECL SQLite extensions 1.0.3 and older (1.0.3 is the
diff --git a/Auth/OpenID/SReg.php b/Auth/OpenID/SReg.php
index 0176516..b370fdf 100644
--- a/Auth/OpenID/SReg.php
+++ b/Auth/OpenID/SReg.php
@@ -2,35 +2,43 @@
 
 /**
  * Simple registration request and response parsing and object
- * representation
+ * representation.
  *
  * This module contains objects representing simple registration
  * requests and responses that can be used with both OpenID relying
  * parties and OpenID providers.
  *
  * 1. The relying party creates a request object and adds it to the
- *    C{L{AuthRequest<openid.consumer.consumer.AuthRequest>}} object
- *    before making the C{checkid_} request to the OpenID provider::
+ * {@link Auth_OpenID_AuthRequest} object before making the
+ * checkid request to the OpenID provider:
  *
- *     auth_request.addExtension(SRegRequest(required=['email']))
+ *   $sreg_req = Auth_OpenID_SRegRequest::build(array('email'));
+ *   $auth_request->addExtension($sreg_req);
  *
- * 2. The OpenID provider extracts the simple registration request from
- *    the OpenID request using C{L{SRegRequest.fromOpenIDRequest}},
- *    gets the user's approval and data, creates a C{L{SRegResponse}}
- *    object and adds it to the C{id_res} response::
+ * 2. The OpenID provider extracts the simple registration request
+ * from the OpenID request using {@link
+ * Auth_OpenID_SRegRequest::fromOpenIDRequest}, gets the user's
+ * approval and data, creates an {@link Auth_OpenID_SRegResponse}
+ * object and adds it to the id_res response:
  *
- *    sreg_req = SRegRequest.fromOpenIDRequest(checkid_request.message)
- *    // [ get the user's approval and data, informing the user that
- *    //   the fields in sreg_response were requested ]
- *    sreg_resp = SRegResponse.extractResponse(sreg_req, user_data)
- *    sreg_resp.addToOpenIDResponse(openid_response)
+ *   $sreg_req = Auth_OpenID_SRegRequest::fromOpenIDRequest($checkid_request->message);
+ *   // [ get the user's approval and data, informing the user that
+ *   //   the fields in sreg_response were requested ]
+ *   $sreg_resp = Auth_OpenID_SRegResponse::extractResponse($sreg_req, $user_data);
+ *   $sreg_resp->addToOpenIDResponse($openid_response);
  *
- * 3. The relying party uses C{L{SRegResponse.fromSuccessResponse}} to
- *    extract the data from the OpenID response::
+ * 3. The relying party uses {@link
+ * Auth_OpenID_SRegResponse::fromSuccessResponse} to extract the data
+ * from the OpenID response:
  *
- *     sreg_resp = SRegResponse.fromSuccessResponse(success_response)
+ *   $sreg_resp = Auth_OpenID_SRegResponse::fromSuccessResponse($success_response);
+ *
+ * @package OpenID
  */
 
+/**
+ * Import message and extension internals.
+ */
 require_once 'Auth/OpenID/Message.php';
 require_once 'Auth/OpenID/Extension.php';
 
@@ -89,6 +97,12 @@ function Auth_OpenID_supportsSReg(&$endpoint)
             $endpoint->usesExtension(Auth_OpenID_SREG_NS_URI_1_0));
 }
 
+/**
+ * A base class for classes dealing with Simple Registration protocol
+ * messages.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_SRegBase extends Auth_OpenID_Extension {
     /**
      * Extract the simple registration namespace URI from the given
@@ -102,6 +116,8 @@ class Auth_OpenID_SRegBase extends Auth_OpenID_Extension {
      * Returns the sreg namespace URI for the supplied message. The
      * message may be modified to define a simple registration
      * namespace.
+     *
+     * @access private
      */
     function _getSRegNS(&$message)
     {
@@ -145,14 +161,14 @@ class Auth_OpenID_SRegBase extends Auth_OpenID_Extension {
  * optional: A list of the optional fields in this simple registration
  * request
  *
- * @ivar policy_url: The policy URL that was provided with the request
+ * @package OpenID
  */
 class Auth_OpenID_SRegRequest extends Auth_OpenID_SRegBase {
 
     var $ns_alias = 'sreg';
 
     /**
-     * Initialize an empty simple registration request
+     * Initialize an empty simple registration request.
      */
     function build($required=null, $optional=null,
                    $policy_url=null,
@@ -215,18 +231,18 @@ class Auth_OpenID_SRegRequest extends Auth_OpenID_SRegBase {
      * and add them to this object.
      *
      * This method is essentially the inverse of
-     * C{L{getExtensionArgs}}. This method restores the serialized
-     * simple registration request fields.
+     * getExtensionArgs. This method restores the serialized simple
+     * registration request fields.
      *
      * If you are extracting arguments from a standard OpenID
-     * checkid_* request, you probably want to use
-     * C{L{fromOpenIDRequest}}, which will extract the sreg namespace
-     * and arguments from the OpenID request. This method is intended
-     * for cases where the OpenID server needs more control over how
-     * the arguments are parsed than that method provides.
+     * checkid_* request, you probably want to use fromOpenIDRequest,
+     * which will extract the sreg namespace and arguments from the
+     * OpenID request. This method is intended for cases where the
+     * OpenID server needs more control over how the arguments are
+     * parsed than that method provides.
      *
-     * >>> args = message.getArgs(ns_uri)
-     * >>> request.parseExtensionArgs(args)
+     * $args == $message->getArgs($ns_uri);
+     * $request->parseExtensionArgs($args);
      *
      * $args: The unqualified simple registration arguments
      *
@@ -386,6 +402,8 @@ class Auth_OpenID_SRegRequest extends Auth_OpenID_SRegBase {
  * inside of an OpenID C{id_res} response. This object will be created
  * by the OpenID server, added to the C{id_res} response object, and
  * then extracted from the C{id_res} message by the Consumer.
+ *
+ * @package OpenID
  */
 class Auth_OpenID_SRegResponse extends Auth_OpenID_SRegBase {
 
@@ -414,7 +432,6 @@ class Auth_OpenID_SRegResponse extends Auth_OpenID_SRegBase {
      * dictionary from unqualified simple registration field name to
      * string (unicode) value. For instance, the nickname should be
      * stored under the key 'nickname'.
-     *
      */
     function extractResponse($request, $data)
     {
diff --git a/Auth/OpenID/Server.php b/Auth/OpenID/Server.php
index d3f384f..9a37c48 100644
--- a/Auth/OpenID/Server.php
+++ b/Auth/OpenID/Server.php
@@ -57,7 +57,7 @@
  * For example:
  *
  *   //  when request is a checkid_* request
- *   response = request.answer(True)
+ *   $response = $request->answer(true);
  *   // this will a signed 'openid.sreg.timezone' parameter to the response
  *   response.addField('sreg', 'timezone', 'America/Los_Angeles')
  *
@@ -267,6 +267,12 @@ class Auth_OpenID_ServerError {
     }
 }
 
+/**
+ * Error returned by the server code when a return_to is absent from a
+ * request.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_NoReturnToError extends Auth_OpenID_ServerError {
     function Auth_OpenID_NoReturnToError($message = null,
                                          $text = "No return_to URL available")
@@ -408,6 +414,11 @@ class Auth_OpenID_CheckAuthRequest extends Auth_OpenID_Request {
     }
 }
 
+/**
+ * A class implementing plaintext server sessions.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_PlainTextServerSession {
     /**
      * An object that knows how to handle association requests with no
@@ -428,6 +439,11 @@ class Auth_OpenID_PlainTextServerSession {
     }
 }
 
+/**
+ * A class implementing DH-SHA1 server sessions.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_DiffieHellmanSHA1ServerSession {
     /**
      * An object that knows how to handle association requests with
@@ -524,6 +540,11 @@ class Auth_OpenID_DiffieHellmanSHA1ServerSession {
     }
 }
 
+/**
+ * A class implementing DH-SHA256 server sessions.
+ *
+ * @package OpenID
+ */
 class Auth_OpenID_DiffieHellmanSHA256ServerSession
       extends Auth_OpenID_DiffieHellmanSHA1ServerSession {
 
diff --git a/Auth/Yadis/Manager.php b/Auth/Yadis/Manager.php
index df0fbbf..1bf39f8 100644
--- a/Auth/Yadis/Manager.php
+++ b/Auth/Yadis/Manager.php
@@ -70,10 +70,14 @@ class Auth_Yadis_PHPSession {
  * for dumb objects that just need to have attributes set.  The idea
  * is that you'll subclass this and override $this->check($data) ->
  * bool to implement your own session data validation.
+ *
+ * @package OpenID
  */
 class Auth_Yadis_SessionLoader {
     /**
      * Override this.
+     *
+     * @access private
      */
     function check($data)
     {
@@ -87,6 +91,8 @@ class Auth_Yadis_SessionLoader {
      * $this->requiredKeys().  Returns null if $this->check($data)
      * evaluates to false.  Returns null if $this->newObject()
      * evaluates to false.
+     *
+     * @access private
      */
     function fromSession($data)
     {
@@ -124,6 +130,8 @@ class Auth_Yadis_SessionLoader {
      * Prepares the data array by making any necessary changes.
      * Returns an array whose keys and values will be used to update
      * the original data array before calling $this->newObject($data).
+     *
+     * @access private
      */
     function prepareForLoad($data)
     {
@@ -135,6 +143,8 @@ class Auth_Yadis_SessionLoader {
      * session data to construct it if necessary.  The object need
      * only be created; $this->fromSession() will take care of setting
      * the object's attributes.
+     *
+     * @access private
      */
     function newObject($data)
     {
@@ -146,6 +156,8 @@ class Auth_Yadis_SessionLoader {
      * of $obj.  If $this->prepareForSave($obj) returns an array, its keys
      * and values are used to update the $data array of attributes
      * from $obj.
+     *
+     * @access private
      */
     function toSession($obj)
     {
@@ -167,6 +179,8 @@ class Auth_Yadis_SessionLoader {
 
     /**
      * Override this.
+     *
+     * @access private
      */
     function prepareForSave($obj)
     {
@@ -176,6 +190,8 @@ class Auth_Yadis_SessionLoader {
 
 /**
  * A concrete loader implementation for Auth_OpenID_ServiceEndpoints.
+ *
+ * @package OpenID
  */
 class Auth_OpenID_ServiceEndpointLoader extends Auth_Yadis_SessionLoader {
     function newObject($data)
@@ -201,6 +217,8 @@ class Auth_OpenID_ServiceEndpointLoader extends Auth_Yadis_SessionLoader {
 
 /**
  * A concrete loader implementation for Auth_Yadis_Managers.
+ *
+ * @package OpenID
  */
 class Auth_Yadis_ManagerLoader extends Auth_Yadis_SessionLoader {
     function requiredKeys()
diff --git a/Auth/Yadis/Yadis.php b/Auth/Yadis/Yadis.php
index 064b5e2..077e569 100644
--- a/Auth/Yadis/Yadis.php
+++ b/Auth/Yadis/Yadis.php
@@ -40,7 +40,11 @@ define('Auth_Yadis_CONTENT_TYPE', 'application/xrds+xml');
  */
 define('Auth_Yadis_HEADER_NAME', 'X-XRDS-Location');
 
-// Contains the result of performing Yadis discovery on a URI
+/**
+ * Contains the result of performing Yadis discovery on a URI.
+ *
+ * @package OpenID
+ */
 class Auth_Yadis_DiscoveryResult {
 
     // The URI that was passed to the fetcher