Changed @return to @retval.

2012-01-27 21:40:21 -06:00
parent 02e6dc33ed
commit 7d7ed2f23b
13 changed files with 79 additions and 79 deletions
--- a/src/HPCloud/Bootstrap.php
+++ b/src/HPCloud/Bootstrap.php
@@ -161,7 +161,7 @@ class Bootstrap {
   *   The name of the configuration option to get.
   * @param mixed $default
   *   The default value to return if the name is not found.
-   * @return mixed
+   * @retval mixed
   *   The value, if found; or the default, if set; or NULL.
   */
  public static function config($name = NULL, $default = NULL) {
@@ -185,7 +185,7 @@ class Bootstrap {
   *
   * @param string $name
   *   The name of the item to check for.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the named option is set, FALSE otherwise. Note that the value may
   *   be falsey (FALSE, 0, etc.), but if the value is NULL, this will return
   *   false.
--- a/src/HPCloud/Services/IdentityServices.php
+++ b/src/HPCloud/Services/IdentityServices.php
@@ -182,7 +182,7 @@ class IdentityServices {
   * This includes version number, so in that regard it is not an identical
   * URL to the one passed into the constructor.
   *
-   * @return string
+   * @retval string
   *   The complete URL to the identity services endpoint.
   */
  public function url() {
@@ -217,7 +217,7 @@ class IdentityServices {
   * @param array $ops
   *   An associative array of authentication operations and their respective
   *   parameters.
-   * @return string
+   * @retval string
   *   The token. This is returned for simplicity. The full response is used
   *   to populate this object's service catalog, etc. The token is also
   *   retrievable with token().
@@ -328,7 +328,7 @@ class IdentityServices {
   * @param string $tenantId
   *   A valid tenant ID. This will be used to associate a tenant's services
   *   with this token.
-   * @return string
+   * @retval string
   *   The auth token.
   * @throws \HPCloud\Transport\AuthorizationException
   *   If authentication failed.
@@ -357,7 +357,7 @@ class IdentityServices {
   * This will not be populated until after one of the authentication
   * methods has been run.
   *
-   * @return string
+   * @retval string
   *   The token ID to be used in subsequent calls.
   */
  public function token() {
@@ -373,7 +373,7 @@ class IdentityServices {
   * This will not be populated until after an authentication method has been
   * run.
   *
-   * @return string
+   * @retval string
   *   The tenant ID if available, or NULL.
   */
  public function tenantId() {
@@ -405,7 +405,7 @@ class IdentityServices {
   *
   * This will not be populated until after authentication has been done.
   *
-   * @returns array
+   * @retvals array
   *   An associative array of details.
   */
  public function tokenDetails() {
@@ -477,7 +477,7 @@ class IdentityServices {
   *
   * @todo Paging on the service catalog is not yet implemented.
   *
-   * @return array
+   * @retval array
   *   An associative array representing
   *   the service catalog.
   */
@@ -524,7 +524,7 @@ class IdentityServices {
   *
   * This will not have data until after authentication has been done.
   *
-   * @return array
+   * @retval array
   *   An associative array, as described above.
   */
  public function user() {
@@ -557,7 +557,7 @@ class IdentityServices {
   *
   * Note that this method invokes a new request against the remote server.
   *
-   * @return array
+   * @retval array
   *   An indexed array of tenant info. Each entry will be an associative
   *   array containing tenant details.
   * @throws \HPCloud\Transport\AuthorizationException
@@ -611,7 +611,7 @@ class IdentityServices {
   *   empty string (`''`), the present token will be "unscoped" and its tenant
   *   ID will be removed.
   *
-   * @return string
+   * @retval string
   *   The authentication token.
   * @throws \HPCloud\Transport\AuthorizationException
   *   If authentication failed.
--- a/src/HPCloud/Storage/ObjectStorage.php
+++ b/src/HPCloud/Storage/ObjectStorage.php
@@ -152,7 +152,7 @@ class ObjectStorage {
  /**
   * Get the authentication token.
   *
-   * @return string
+   * @retval string
   *   The authentication token.
   */
  public function token() {
@@ -162,7 +162,7 @@ class ObjectStorage {
  /**
   * Get the URL endpoint.
   *
-   * @return string
+   * @retval string
   *   The URL that is the endpoint for this service.
   */
  public function url() {
@@ -198,7 +198,7 @@ class ObjectStorage {
   * @param string $marker
   *   The name of the last object seen. Used when paging.
   *
-   * @return array
+   * @retval array
   *   An associative array of containers, where the key is the
   *   container's name and the value is an
   *   \HPCloud\Storage\ObjectStorage\Container object. Results are
@@ -233,7 +233,7 @@ class ObjectStorage {
   *
   * @param string $name
   *   The name of the container to load.
-   * @return \HPCloud\Storage\ObjectStorage\Container
+   * @retval \HPCloud\Storage\ObjectStorage\Container
   *   A container.
   * @throws \HPCloud\Transport\FileNotFoundException
   *   if the named container is not found on the remote server.
@@ -261,7 +261,7 @@ class ObjectStorage {
   *
   * @param string $name
   *   The name of the container to test.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the container exists, FALSE if it does not.
   * @throws \HPCloud\Exception
   *   If an unexpected network error occurs.
@@ -332,7 +332,7 @@ class ObjectStorage {
   *   non-public (private). To change this behavior, you can add a
   *   custom ACL. To make the container publically readable, you can
   *   use this: `ACL::makePublic()`.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the container was created, FALSE if the container was not
   *   created because it already exists.
   */
@@ -383,7 +383,7 @@ class ObjectStorage {
   * @param \HPCloud\Storage\ObjectStorage\ACL $acl
   *   An ACL. To make the container publically readable, use
   *   ACL::makePublic().
-   * @return boolean
+   * @retval boolean
   *   TRUE if the cointainer was created, FALSE otherwise.
   */
  public function changeContainerACL($name, ACL $acl) {
@@ -404,7 +404,7 @@ class ObjectStorage {
   *
   * @param string $name
   *   The name of the container.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the container was deleted, FALSE if the container was not
   *   found (and hence, was not deleted).
   * @throws \HPCloud\Storage\ObjectStorage\ContainerNotEmptyException
@@ -450,7 +450,7 @@ class ObjectStorage {
   * - The total bytes used by this Object Storage instance (`bytes`).
   * - The number of containers (`count`).
   *
-   * @return array
+   * @retval array
   *  An associative array of account info. Typical keys are:
   *  - bytes: Bytes consumed by existing content.
   *  - containers: Number of containers.
--- a/src/HPCloud/Storage/ObjectStorage/ACL.php
+++ b/src/HPCloud/Storage/ObjectStorage/ACL.php
@@ -126,7 +126,7 @@ class ACL {
   *
   * - READ to any host, with container listings.
   *
-   * @return \HPCloud\Storage\ObjectStorage\ACL
+   * @retval \HPCloud\Storage\ObjectStorage\ACL
   *   an ACL object with the appopriate permissions set.
   */
  public static function makePublic() {
@@ -146,7 +146,7 @@ class ACL {
   * This does not grant any permissions. OpenStack interprets an object
   * with no permissions as a private object.
   *
-   * @return \HPCloud\Storage\ObjectStorage\ACL
+   * @retval \HPCloud\Storage\ObjectStorage\ACL
   *   an ACL object with the appopriate permissions set.
   */
  public static function makeNonPublic() {
@@ -205,7 +205,7 @@ class ACL {
   *   The permission (ACL::READ, ACL::WRITE).
   * @param string $rule
   *   The string rule to parse.
-   * @return array
+   * @retval array
   *   The rule as an array.
   */
  public static function parseRule($perm, $rule) {
@@ -353,7 +353,7 @@ class ACL {
  /**
   * Get the rules array for this ACL.
   *
-   * @return array
+   * @retval array
   *   An array of associative arrays of rules.
   */
  public function rules() {
@@ -457,7 +457,7 @@ class ACL {
   * This returns TRUE only if this ACL does not grant any permissions
   * at all.
   *
-   * @return boolean
+   * @retval boolean
   *   TRUE if this is private (non-public), FALSE if
   *   any permissions are granted via this ACL.
   */
--- a/src/HPCloud/Storage/ObjectStorage/Container.php
+++ b/src/HPCloud/Storage/ObjectStorage/Container.php
@@ -82,7 +82,7 @@ class Container implements \Countable, \IteratorAggregate {
   *   ASCII-armored with no newlines.
   * @param string $prefix
   *   A prefix for the metadata headers.
-   * @return array
+   * @retval array
   *   An array of headers.
   * @see http://docs.openstack.org/bexar/openstack-object-storage/developer/content/ch03s03.html#d5e635
   * @see http://docs.openstack.org/bexar/openstack-object-storage/developer/content/ch03s03.html#d5e700
@@ -115,7 +115,7 @@ class Container implements \Countable, \IteratorAggregate {
   *   An associative array of HTTP headers.
   * @param string $prefix
   *   The prefix on metadata headers.
-   * @return array
+   * @retval array
   *   An associative array of name/value attribute pairs.
   */
  public static function extractHeaderAttributes($headers, $prefix = NULL) {
@@ -189,7 +189,7 @@ class Container implements \Countable, \IteratorAggregate {
   * @param string $url
   *   The base URL. The container name is automatically appended to
   *   this at construction time.
-   * @return Container
+   * @retval Container
   *   The Container object, initialized and ready for use.
   */
  public static function newFromResponse($name, $response, $token, $url) {
@@ -219,7 +219,7 @@ class Container implements \Countable, \IteratorAggregate {
  /**
   * Get the name of this container.
   *
-   * @return string
+   * @retval string
   *   The name of the container.
   */
  public function name() {
@@ -229,7 +229,7 @@ class Container implements \Countable, \IteratorAggregate {
  /**
   * Get the number of bytes in this container.
   *
-   * @return int
+   * @retval int
   *   The number of bytes in this container.
   */
  public function bytes() {
@@ -251,7 +251,7 @@ class Container implements \Countable, \IteratorAggregate {
   * listings do not supply the metadata, while loading a container
   * directly does.
   *
-   * @return array
+   * @retval array
   *   An array of metadata name/value pairs.
   */
  public function metadata() {
@@ -298,7 +298,7 @@ class Container implements \Countable, \IteratorAggregate {
   * ?>
   * @endcode
   *
-   * @return int
+   * @retval int
   *   The number of items in this container.
   */
  public function count() {
@@ -314,7 +314,7 @@ class Container implements \Countable, \IteratorAggregate {
   *
   * @param \HPCloud\Storage\ObjectStorage\Object $obj
   *   The object to store.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the object was saved.
   * @throws \HPCloud\Transport\LengthRequiredException
   *   if the Content-Length could not be determined and chunked
@@ -432,7 +432,7 @@ class Container implements \Countable, \IteratorAggregate {
   * @param \HPCloud\Storage\ObjectStorage\Object $obj
   *   The object to update.
   *
-   * @return boolean
+   * @retval boolean
   *   TRUE if the metadata was updated.
   *
   * @throws \HPCloud\Transport\FileNotFoundException
@@ -541,7 +541,7 @@ class Container implements \Countable, \IteratorAggregate {
   *
   * @param string $name
   *   The name of the object to load.
-   * @return \HPCloud\Storage\ObjectStorage\RemoteObject
+   * @retval \HPCloud\Storage\ObjectStorage\RemoteObject
   *   A remote object with the content already stored locally.
   */
  public function object($name) {
@@ -591,7 +591,7 @@ class Container implements \Countable, \IteratorAggregate {
   *
   * @param string $name
   *   The name of the object to fetch.
-   * @return \HPCloud\Storage\ObjectStorage\RemoteObject
+   * @retval \HPCloud\Storage\ObjectStorage\RemoteObject
   *   A remote object ready for use.
   */
  public function remoteObject($name) {
@@ -640,7 +640,7 @@ class Container implements \Countable, \IteratorAggregate {
   * @param string $maker
   *   The name of the object to start with. The query will begin with
   *   the next object AFTER this one.
-   * @return array
+   * @retval array
   *   List of RemoteObject or Subdir instances.
   */
  public function objects($limit = NULL, $marker = NULL) {
@@ -701,7 +701,7 @@ class Container implements \Countable, \IteratorAggregate {
   * @param string $marker
   *   The name of the object to start with. The query will begin with
   *   the next object AFTER this one.
-   * @return array
+   * @retval array
   *   List of RemoteObject or Subdir instances.
   */
  public function objectsWithPrefix($prefix, $delimiter = '/', $limit = NULL, $marker = NULL) {
@@ -766,7 +766,7 @@ class Container implements \Countable, \IteratorAggregate {
   * Container was set to be public (See 
   * ObjectStorage::createContainer()) will be accessible by this URL.
   *
-   * @return
+   * @retval
   */
  public function url() {
    return $this->url;
@@ -786,7 +786,7 @@ class Container implements \Countable, \IteratorAggregate {
   * ObjectStorage methods.
   *
   * @todo Determine how to get the ACL from JSON data.
-   * @return \HPCloud\Storage\ObjectStorage\ACL
+   * @retval \HPCloud\Storage\ObjectStorage\ACL
   *   An ACL, or NULL if the ACL could not be retrieved.
   */
  public function acl() {
@@ -902,7 +902,7 @@ class Container implements \Countable, \IteratorAggregate {
   *
   * @param string $name
   *   The name of the object to remove.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the file was deleted, FALSE if no such file is found.
   */
  public function delete($name) {
--- a/src/HPCloud/Storage/ObjectStorage/Object.php
+++ b/src/HPCloud/Storage/ObjectStorage/Object.php
@@ -138,7 +138,7 @@ class Object {
   *
   * This returns an associative array of all metadata for this object.
   *
-   * @return array
+   * @retval array
   *   An associative array of metadata. This may be empty.
   */
  public function metadata() {
@@ -170,7 +170,7 @@ class Object {
   * Returns the name of an object. If the name has been overwritten
   * using setName(), this will return the latest (overwritten) name.
   *
-   * @return string
+   * @retval string
   *   The name of the object.
   */
  public function name() {
@@ -214,7 +214,7 @@ class Object {
   *
   * This returns the currently set content type.
   *
-   * @return string
+   * @retval string
   *   The content type, including any additional options.
   */
  public function contentType() {
@@ -268,7 +268,7 @@ class Object {
   * When extending this class, you should make sure that this function
   * returns the entire contents of an object.
   *
-   * @return string
+   * @retval string
   *   The content of the file.
   */
  public function content() {
@@ -303,7 +303,7 @@ class Object {
   * When extending this class, generate an ETag by creating an MD5 of
   * the entire object's content (but not the metadata or name).
   *
-   * @return string
+   * @retval string
   *   An MD5 value as a string of 32 hex digits (0-9a-f).
   */
  public function eTag() {
@@ -339,7 +339,7 @@ class Object {
   * Encoding is used to indicate how a file was encoded or compressed.
   * See setEncoding() for more information.
   *
-   * @return string
+   * @retval string
   *   The encoding type.
   */
  public function encoding() {
@@ -376,7 +376,7 @@ class Object {
   *
   * See setDisposition() for discussion.
   *
-   * @return string
+   * @retval string
   *   The disposition string, or NULL if none is set.
   */
  public function disposition() {
@@ -446,7 +446,7 @@ class Object {
   * The contentLength() method is not called for chunked transfers. So
   * if this returns TRUE, contentLength() is ignored.
   *
-   * @return boolean
+   * @retval boolean
   *   TRUE to recommend chunked transfer, FALSE otherwise.
   */
  public function isChunked() {
--- a/src/HPCloud/Storage/ObjectStorage/RemoteObject.php
+++ b/src/HPCloud/Storage/ObjectStorage/RemoteObject.php
@@ -173,7 +173,7 @@ class RemoteObject extends Object {
   * This returns the array of minimally processed HTTP headers that
   * were sent from the server.
   *
-   * @return array
+   * @retval array
   *   An associative array of header names and values.
   */
  public function headers() {
@@ -195,7 +195,7 @@ class RemoteObject extends Object {
   *
   * Be wary of using this method with large files.
   *
-   * @return string
+   * @retval string
   *   The contents of the file as a string.
   * @throws \HPCloud\Transport\FileNotFoundException
   *   when the requested content cannot be located on the remote
@@ -261,7 +261,7 @@ class RemoteObject extends Object {
   *   If this is set to TRUE, any existing local modifications will be ignored
   *   and the content will be refreshed from the server. Any
   *   local changes to the object will be discarded.
-   * @return resource
+   * @retval resource
   *   A handle to the stream, which is already opened and positioned at
   *   the beginning of the stream.
   */
@@ -324,7 +324,7 @@ class RemoteObject extends Object {
   * Importantly, this indicates whether the object <i>will</i> cache
   * its contents, not whether anything is actually cached.
   *
-   * @return boolean
+   * @retval boolean
   *   TRUE if caching is enabled, FALSE otherwise.
   */
  public function isCaching() {
@@ -366,7 +366,7 @@ class RemoteObject extends Object {
   * returned by the remote server, and comparing that to the server's
   * supplied ETag hash.
   *
-   * @return boolean
+   * @retval boolean
   *   TRUE if this is verifying, FALSE otherwise.
   */
  public function isVerifyingContent() {
@@ -445,7 +445,7 @@ class RemoteObject extends Object {
   *   cause the remote host to return the object in the response body.
   *   The response body is not handled, though. If this is set to
   *   FALSE, a HEAD request is sent, and no body is returned.
-   * @return \HPCloud\Transport\Response
+   * @retval \HPCloud\Transport\Response
   *   containing the object metadata and (depending on the
   *   $fetchContent flag) optionally the data.
   */
--- a/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php
+++ b/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php
@@ -323,7 +323,7 @@ class StreamWrapper {
   *   The URL to open.
   * @param int $options
   *   Unused.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the directory is opened, FALSE otherwise.
   */
  public function dir_opendir($path, $options) {
@@ -363,7 +363,7 @@ class StreamWrapper {
   *
   * This gets a single line from the directory.
   *
-   * @return string
+   * @retval string
   *   The name of the resource or FALSE when the directory has no more
   *   entries.
   */
@@ -425,7 +425,7 @@ class StreamWrapper {
   *   A swift URL that exists on the remote.
   * @param string $path_to
   *   A swift URL to another path.
-   * @return boolean
+   * @retval boolean
   *   TRUE on success, FALSE otherwise.
   */
  public function rename($path_from, $path_to) {
@@ -470,7 +470,7 @@ class StreamWrapper {
   * the lower-level buffer objects, this function can have unexpected
   * side effects.
   *
-   * @return resource
+   * @retval resource
   *   this returns the underlying stream.
   */
  public function stream_cast($cast_as) {
@@ -507,7 +507,7 @@ class StreamWrapper {
   *
   * See stream_seek().
   *
-   * @return boolean
+   * @retval boolean
   *   TRUE if it has reached the end, FALSE otherwise.
   */
  public function stream_eof() {
@@ -755,7 +755,7 @@ class StreamWrapper {
   *
   * @param int $count
   *   The number of bytes to read (usually 8192).
-   * @return string
+   * @retval string
   *   The data read.
   */
  public function stream_read($count) {
@@ -858,7 +858,7 @@ class StreamWrapper {
   *
   * See ftell() and fseek().
   *
-   * @return int
+   * @retval int
   *   The current position in the stream.
   */
  public function stream_tell() {
@@ -874,7 +874,7 @@ class StreamWrapper {
   *
   * @param string $data
   *   Data to write to the stream.
-   * @return int
+   * @retval int
   *   The number of bytes written. 0 indicates and error.
   */
  public function stream_write($data) {
@@ -896,7 +896,7 @@ class StreamWrapper {
   *
   * @param string $path
   *   The URL.
-   * @return boolean
+   * @retval boolean
   *   TRUE if the file was deleted, FALSE otherwise.
   */
  public function unlink($path) {
@@ -1140,7 +1140,7 @@ class StreamWrapper {
   *   it up in the Bootstrap config.
   * @param mixed $default
   *   The default value to return if no config param was found.
-   * @return mixed
+   * @retval mixed
   *   The discovered result, or $default if specified, or NULL if
   *   no $default is specified.
   */
@@ -1187,7 +1187,7 @@ class StreamWrapper {
   *
   * @param string $url
   *   A Swift URL.
-   * @return array
+   * @retval array
   *   An array as documented in parse_url().
   */
  protected function parseUrl($url) {
--- a/src/HPCloud/Storage/ObjectStorage/Subdir.php
+++ b/src/HPCloud/Storage/ObjectStorage/Subdir.php
@@ -40,7 +40,7 @@ class Subdir {
   *
   * The path is delimited using the string returned by delimiter().
   *
-   * @return string
+   * @retval string
   *   The path.
   */
  public function path() {
@@ -49,7 +49,7 @@ class Subdir {
  /**
   * Get the delimiter used by the server.
   *
-   * @return string
+   * @retval string
   *   The value used as a delimiter.
   */
  public function delimiter() {
--- a/src/HPCloud/Transport.php
+++ b/src/HPCloud/Transport.php
@@ -18,7 +18,7 @@ class Transport {
  /**
   * Get an instance of a Transporter.
   *
-   * @return \HPCloud\Transport\Transporter
+   * @retval \HPCloud\Transport\Transporter
   *   An initialized transporter.
   */
  public static function instance() {
--- a/src/HPCloud/Transport/CURLTransport.php
+++ b/src/HPCloud/Transport/CURLTransport.php
@@ -203,7 +203,7 @@ class CURLTransport implements Transporter {
   *
   * @param resource $file
   *   A file pointer to the file that has the headers.
-   * @return array
+   * @retval array
   *   An array of headers, one header per line.
   */
  protected function fetchHeaders($file) {
--- a/src/HPCloud/Transport/PHPStreamTransport.php
+++ b/src/HPCloud/Transport/PHPStreamTransport.php
@@ -166,7 +166,7 @@ class PHPStreamTransport implements Transporter {
   *
   * @param array $headers
   *   An associative array of header names to header values.
-   * @return string
+   * @retval string
   *   A string containing formatted headers.
   */
  protected function smashHeaders($headers) {
--- a/src/HPCloud/Transport/Response.php
+++ b/src/HPCloud/Transport/Response.php
@@ -119,7 +119,7 @@ class Response {
   * the handle returned by file() will also be closed
   * (they are one and the same).
   *
-   * @return resource
+   * @retval resource
   *   A file handle.
   */
  public function file() {
@@ -137,7 +137,7 @@ class Response {
   * to keep memory usage low, we don't want to store the
   * entire content in a string.
   *
-   * @return string
+   * @retval string
   *   The contents of the response body.
   */
  public function content() {
@@ -170,7 +170,7 @@ class Response {
   * Some return extra information on the processing of the
   * data.
   *
-   * @return array
+   * @retval array
   *   An associative array of metadata about the
   *   transaction resulting in this response.
   */
@@ -222,7 +222,7 @@ class Response {
   * Redirects are typically followed, and thus rarely (if ever)
   * appear in a Response object.
   *
-   * @return int
+   * @retval int
   *   The HTTP code, e.g. 200 or 202.
   */
  public function status() {
@@ -235,7 +235,7 @@ class Response {
   * Typically these follow the HTTP protocol specification's
   * recommendations. e.g. 200 returns 'OK'.
   *
-   * @return string
+   * @retval string
   *  A server-generated status message.
   */
  public function statusMessage() {
@@ -247,7 +247,7 @@ class Response {
   *
   * Example: HTTP/1.1
   *
-   * @return string
+   * @retval string
   *   The protocol name and version.
   */
  public function protocol() {
@@ -264,7 +264,7 @@ class Response {
   * @param array $headerArray
   *   An indexed array of headers, as returned by the PHP stream
   *   library.
-   * @return array
+   * @retval array
   *   An associative array of header name/value pairs.
   */
  protected function parseHeaders($headerArray) {