Added support for @return in addition to @retval. @retval is a doxygen convention we use when generating our api docs. But, phpdoc uses @return which is what IDEs typically support on introspection. To better support introspection we now have both.

src/HPCloud/Bootstrap.php

@@ -285,6 +285,7 @@ class Bootstrap {
    * @param mixed $default
    *   The default value to return if the name is not found.
    * @retval mixed
+   * @return mixed
    *   The value, if found; or the default, if set; or NULL.
    */
   public static function config($name = NULL, $default = NULL) {
@@ -315,6 +316,7 @@ class Bootstrap {
    * @param string $name
    *   The name of the item to check for.
    * @retval boolean
+   * @return 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.
@@ -333,6 +335,7 @@ class Bootstrap {
    *   Whether to force the generation of a new object even if one is already
    *   cached.
    * @retval HPCloud::Services::IdentityService
+   * @return \HPCloud\Services\:IdentityService
    *   An authenticated ready to use HPCloud::Services::IdentityService object.
    * @throws HPCloud::Exception
    *   When the needed configuration to authenticate is not available.

src/HPCloud/Services/DBaaS.php

@@ -137,6 +137,7 @@ class DBaaS {
    * Get the project ID for this session.
    *
    * @retval string
+   * @return string
    *   The project ID.
    */
   public function projectId() {
@@ -147,6 +148,7 @@ class DBaaS {
    * Get the endpoint URL to the DBaaS session.
    *
    * @retval string
+   * @return string
    *   The URL.
    */
   public function url() {

src/HPCloud/Services/DBaaS/Instance.php

@@ -79,7 +79,8 @@ class Instance extends Operations {
    *- medium
    * @param array $typeSpec
    *   A typespec array. Currently, only 'mysql', '5.5' is supported.
-   * @retval object HPCloud::Services::DBaaS::InstanceDetails
+   * @retval HPCloud::Services::DBaaS::InstanceDetails
+   * @return \HPCloud\Services\DBaaS\InstanceDetails
    *   The details of creation, including login and password info.
    * @see http://api-docs.hpcloud.com/hpcloud-dbaas/1.0/content/instance-create.html
    */
@@ -132,6 +133,7 @@ class Instance extends Operations {
    * Reset the primary password on this instance.
    *
    * @retval string
+   * @return string
    *   The new (autogenerated) password.
    */
   public function resetPassword($instanceId) {

src/HPCloud/Services/DBaaS/InstanceDetails.php

@@ -74,6 +74,7 @@ class InstanceDetails {
    * Get the name of this instance.
    *
    * @retval string
+   * @return string
    *   The name of the instance.
    */
   public function name() {
@@ -84,6 +85,7 @@ class InstanceDetails {
    * Get the ID of the instance.
    *
    * @retval string
+   * @return string
    *   The ID.
    */
   public function id() {
@@ -96,6 +98,7 @@ class InstanceDetails {
    * This may only be set during CREATE or DESCRIBE results.
    *
    * @retval string
+   * @return string
    *   A string indicating the creation time.
    *   Format is in ISO date format.
    */
@@ -115,6 +118,7 @@ class InstanceDetails {
    *- restarting: Instance has been restarted, and is still coming online.
    *
    * @retval string
+   * @return string
    *   A short status message.
    */
   public function status() {
@@ -129,6 +133,7 @@ class InstanceDetails {
    * checking that status() returns 'running'.
    *
    * @retval boolean
+   * @return boolean
    *   TRUE if this is running, FALSE otherwise.
    */
   public function isRunning() {
@@ -148,6 +153,7 @@ class InstanceDetails {
    * This returns the DNS name of the host (or possibly an IP address).
    *
    * @retval string
+   * @return string
    *   The FQDN or IP address of the MySQL server.
    */
   public function hostname() {
@@ -177,6 +183,7 @@ class InstanceDetails {
    * Typically this is only available at creation time!
    *
    * @retval string
+   * @return string
    *   The username for the MySQL instance.
    */
   public function username() {
@@ -208,6 +215,7 @@ class InstanceDetails {
    *   This is only returned when a database is first created.
    *
    * @retval string
+   * @return string
    *   A password string.
    */
   public function password() {
@@ -250,6 +258,7 @@ class InstanceDetails {
    * definition.
    *
    * @retval array
+   * @return array
    *   An array of related links to DBaaS URLs.
    */
   public function links() {
@@ -271,6 +280,7 @@ class InstanceDetails {
    *   of PHP use this.
    *
    * @retval string
+   * @return string
    *   The DSN, including driver, host, port, and database name.
    * @todo
    *   At this time, 'mysql' is hard-coded as the driver name. Does this

src/HPCloud/Services/DBaaS/Snapshot.php

@@ -66,6 +66,7 @@ class Snapshot extends Operations {
    *   An optional database instance ID. If set, only snapshots for
    *   the given instance will be returned.
    * @retval array
+   * @return array
    *   An array of HPCloud::Services::DBaaS::SnapshotDetails
    *   instances.
    */
@@ -102,7 +103,8 @@ class Snapshot extends Operations {
    *   A human-readable name for the snapshot. Internally,
    *   a snapshot ID will be used to reference this
    *   snapshot.
-   * @retval object HPCloud::Services::DBaaS::SnapshotDetails
+   * @retval HPCloud::Services::DBaaS::SnapshotDetails
+   * @return \HPCloud\Services\DBaaS\SnapshotDetails
    *   A snapshot details object containing information about
    *   the snapshot.
    */
@@ -130,6 +132,7 @@ class Snapshot extends Operations {
    *   The snapshot ID for the snapshot that should
    *   be deleted.
    * @retval boolean
+   * @return boolean
    *   Returns boolean TRUE on success. Throws one of the 
    *   HPCloud::Exception instances on failure.
    * @throws HPCloud::Exception
@@ -148,7 +151,8 @@ class Snapshot extends Operations {
    * @param string $snapshotId
    *   The snapshot ID.
    *
-   * @retval object HPCloud::Services::DBaaS::SnapshotDetails
+   * @retval HPCloud::Services::DBaaS::SnapshotDetails
+   * @return \HPCloud\Services\DBaaS\SnapshotDetails
    *   The details object.
    */
   public function describe($snapshotId) {

src/HPCloud/Services/DBaaS/SnapshotDetails.php

@@ -54,6 +54,7 @@ class SnapshotDetails {
    * The ID of the snapshot.
    *
    * @retval string
+   * @return string
    *   The ID.
    */
   public function id() {
@@ -66,6 +67,7 @@ class SnapshotDetails {
    * is a snapshot.
    *
    * @retval string
+   * @return string
    *   The database instance ID.
    */
   public function instanceId() {
@@ -75,6 +77,7 @@ class SnapshotDetails {
    * The data upon which this snapshot was created.
    *
    * @retval string
+   * @return string
    *   An ISO data string representing the date and time
    *   that this snapshot was created.
    */
@@ -90,6 +93,7 @@ class SnapshotDetails {
    *   The data returned from this may be in flux during the beta release
    *   of this product.
    * @retval array
+   * @return array
    *   An array of links. Typically, at least an URL to the snapshot should
    *   be provided.
    */

src/HPCloud/Services/IdentityServices.php

@@ -223,6 +223,7 @@ class IdentityServices /*implements Serializable*/ {
    * URL to the one passed into the constructor.
    *
    * @retval string
+   * @return string
    *   The complete URL to the identity services endpoint.
    */
   public function url() {
@@ -258,6 +259,7 @@ class IdentityServices /*implements Serializable*/ {
    *   An associative array of authentication operations and their respective
    *   parameters.
    * @retval string
+   * @return 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().
@@ -383,6 +385,7 @@ class IdentityServices /*implements Serializable*/ {
    *   The tenant Name for this account. This can be obtained through the
    *   HPCloud console.
    * @retval string
+   * @return string
    *   The auth token.
    * @throws HPCloud::Transport::AuthorizationException
    *   If authentication failed.
@@ -416,6 +419,7 @@ class IdentityServices /*implements Serializable*/ {
    * methods has been run.
    *
    * @retval string
+   * @return string
    *   The token ID to be used in subsequent calls.
    */
   public function token() {
@@ -432,6 +436,7 @@ class IdentityServices /*implements Serializable*/ {
    * run.
    *
    * @retval string
+   * @return string
    *   The tenant ID if available, or NULL.
    */
   public function tenantId() {
@@ -450,6 +455,7 @@ class IdentityServices /*implements Serializable*/ {
    * run.
    *
    * @retval string
+   * @return string
    *   The tenant name if available, or NULL.
    */
   public function tenantName() {
@@ -484,6 +490,7 @@ class IdentityServices /*implements Serializable*/ {
    * This will not be populated until after authentication has been done.
    *
    * @retval array
+   * @return array
    *   An associative array of details.
    */
   public function tokenDetails() {
@@ -498,6 +505,7 @@ class IdentityServices /*implements Serializable*/ {
    * mis-configured machine timestamp could give spurious results.
    *
    * @retval boolean
+   * @return boolean
    *   This will return FALSE if there is a current token and it has
    *   not yet expired (according to the date info). In all other cases
    *   it returns TRUE.
@@ -581,6 +589,7 @@ class IdentityServices /*implements Serializable*/ {
    * @todo Paging on the service catalog is not yet implemented.
    *
    * @retval array
+   * @return array
    *   An associative array representing
    *   the service catalog.
    */
@@ -628,6 +637,7 @@ class IdentityServices /*implements Serializable*/ {
    * This will not have data until after authentication has been done.
    *
    * @retval array
+   * @return array
    *   An associative array, as described above.
    */
   public function user() {
@@ -661,6 +671,7 @@ class IdentityServices /*implements Serializable*/ {
    * Note that this method invokes a new request against the remote server.
    *
    * @retval array
+   * @return array
    *   An indexed array of tenant info. Each entry will be an associative
    *   array containing tenant details.
    * @throws HPCloud::Transport::AuthorizationException
@@ -723,6 +734,7 @@ class IdentityServices /*implements Serializable*/ {
    *   ID will be removed.
    *
    * @retval string
+   * @return string
    *   The authentication token.
    * @throws HPCloud::Transport::AuthorizationException
    *   If authentication failed.
@@ -780,6 +792,7 @@ class IdentityServices /*implements Serializable*/ {
    *   name will be removed.
    *
    * @retval string
+   * @return string
    *   The authentication token.
    * @throws HPCloud::Transport::AuthorizationException
    *   If authentication failed.

src/HPCloud/Storage/CDN.php

@@ -149,7 +149,9 @@ class CDN {
    *
    * @param HPCloud::Services::IdentityServices $identity
    *   The identity to use.
-   * @retval object
+   * @retval boolean
+   * @retval HPCloud::Storage::CDN
+   * @return \HPCloud\Storage\CDN|boolean
    *   A CDN object or FALSE if no CDN services could be found
    *   in the catalog.
    */
@@ -195,7 +197,9 @@ class CDN {
    *   A service catalog; see HPCloud::Services::IdentityServices::serviceCatalog().
    * @param string $token
    *   The token.
-   * @retval object
+   * @retval boolean
+   * @retval HPCloud::Storage::CDN
+   * @return boolean|\HPCloud\Storage\CDN
    *   A CDN object or FALSE if no CDN services could be found
    *   in the catalog.
    */
@@ -305,6 +309,7 @@ class CDN {
    *   If this is set to TRUE, then only containers that are
    *   CDN-enabled will be returned.
    * @retval array
+   * @return array
    *   An indexed array of associative arrays. The format of each
    *   associative array is explained on container().
    * @throws HPCloud::Exception
@@ -357,6 +362,7 @@ class CDN {
    * @param string $name
    *   The name of the container to fetch.
    * @retval array
+   * @return array
    *   An associative array in the exact format as in containers.
    */
   public function container($name) {
@@ -412,6 +418,7 @@ class CDN {
    *   If this is passed, then its value will be set to TRUE if the
    *   container was created in the CDN, or FALSE if the container
    *   already existed in CDN.
+   * @retval string
    * @return string
    *   TRUE if the container was created, FALSE if the container was already
    *   added to the CDN (and thus nothing happened).
@@ -450,6 +457,7 @@ class CDN {
    * @param array $attrs
    *   An associative array of attributes.
    * @retval boolean
+   * @return boolean
    *   TRUE if the update was successful.
    * @throws HPCloud::Exception
    *   Possibly throws one of the HTTP exceptions.
@@ -509,6 +517,7 @@ class CDN {
    * @param string $name
    *   The name of the container whose cache should be suspended.
    * @retval boolean
+   * @return boolean
    *   TRUE if the container is disabled.
    * @throws HPCloud::Exception
    *   HTTP exceptions may be thrown if an error occurs.
@@ -535,6 +544,7 @@ class CDN {
    * @param string $name
    *   The Container name.
    * @retval boolean
+   * @return boolean
    *   TRUE if the container was successfully deleted,
    *   FALSE if the container was not removed, but no
    *   error occurred.

src/HPCloud/Storage/ObjectStorage.php

@@ -172,7 +172,8 @@ class ObjectStorage {
    * @param HPCloud::Services::IdentityServices $identity
    *   An identity services object that already has a valid token and a
    *   service catalog.
-   * @retval object ObjectStorage
+   * @retval HPCloud::Storage::ObjectStorage
+   * @return \HPCloud\Storage\ObjectStorage
    *   A new ObjectStorage instance.
    */
   public static function newFromIdentity($identity) {
@@ -196,7 +197,8 @@ class ObjectStorage {
    *   just ObjectStorage::SERVICE_TYPE.
    * @param string $authToken
    *   The auth token returned by IdentityServices.
-   * @retval object ObjectStorage
+   * @retval HPCloud::Storage::ObjectStorage
+   * @return \HPCloud\Storage\ObjectStorage
    *   A new ObjectStorage instance.
    */
   public static function newFromServiceCatalog($catalog, $authToken) {
@@ -286,6 +288,7 @@ class ObjectStorage {
    *   If this is TRUE (default), get the URL to the SSL CDN;
    *   otherwise get the URL to the plain HTTP CDN.
    * @retval string
+   * @return string
    *   The URL to the CDN container, or NULL if no such
    *   URL is found.
    */
@@ -300,6 +303,7 @@ class ObjectStorage {
    * Get the authentication token.
    *
    * @retval string
+   * @return string
    *   The authentication token.
    */
   public function token() {
@@ -310,6 +314,7 @@ class ObjectStorage {
    * Get the URL endpoint.
    *
    * @retval string
+   * @return string
    *   The URL that is the endpoint for this service.
    */
   public function url() {
@@ -346,6 +351,7 @@ class ObjectStorage {
    *   The name of the last object seen. Used when paging.
    *
    * @retval array
+   * @return 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
@@ -387,6 +393,7 @@ class ObjectStorage {
    * @param string $name
    *   The name of the container to load.
    * @retval HPCloud::Storage::ObjectStorage::Container
+   * @return \HPCloud\Storage\ObjectStorage\Container
    *   A container.
    * @throws HPCloud::Transport::FileNotFoundException
    *   if the named container is not found on the remote server.
@@ -422,6 +429,7 @@ class ObjectStorage {
    * @param string $name
    *   The name of the container to test.
    * @retval boolean
+   * @return boolean
    *   TRUE if the container exists, FALSE if it does not.
    * @throws HPCloud::Exception
    *   If an unexpected network error occurs.
@@ -495,6 +503,7 @@ class ObjectStorage {
    * @param array $metadata
    *   An associative array of metadata to attach to the container.
    * @retval boolean
+   * @return boolean
    *   TRUE if the container was created, FALSE if the container was not
    *   created because it already exists.
    */
@@ -558,6 +567,7 @@ class ObjectStorage {
    *   An ACL. To make the container publically readable, use
    *   ACL::makePublic().
    * @retval boolean
+   * @return boolean
    *   TRUE if the cointainer was created, FALSE otherwise.
    */
   public function changeContainerACL($name, ACL $acl) {
@@ -579,6 +589,7 @@ class ObjectStorage {
    * @param string $name
    *   The name of the container.
    * @retval boolean
+   * @return boolean
    *   TRUE if the container was deleted, FALSE if the container was not
    *   found (and hence, was not deleted).
    * @throws HPCloud::Storage::ObjectStorage::ContainerNotEmptyException
@@ -625,6 +636,7 @@ class ObjectStorage {
    * - The number of containers (`count`).
    *
    * @retval array
+   * @return array
    *  An associative array of account info. Typical keys are:
    *  - bytes: Bytes consumed by existing content.
    *  - containers: Number of containers.

src/HPCloud/Storage/ObjectStorage/ACL.php

@@ -152,6 +152,7 @@ class ACL {
    * - READ to any host, with container listings.
    *
    * @retval HPCloud::Storage::ObjectStorage::ACL
+   * @return \HPCloud\Storage\ObjectStorage\ACL
    *   an ACL object with the appopriate permissions set.
    */
   public static function makePublic() {
@@ -172,6 +173,7 @@ class ACL {
    * with no permissions as a private object.
    *
    * @retval HPCloud::Storage::ObjectStorage::ACL
+   * @return \HPCloud\Storage\ObjectStorage\ACL
    *   an ACL object with the appopriate permissions set.
    */
   public static function makeNonPublic() {
@@ -194,7 +196,8 @@ class ACL {
    *
    * @param array $headers
    *   An associative array of headers.
-   * @retval ACL
+   * @retval HPCloud::Storage::ObjectStorage::ACL
+   * @return \HPCloud\Storage\ObjectStorage\ACL
    *   A new ACL.
    */
   public static function newFromHeaders($headers) {
@@ -242,6 +245,7 @@ class ACL {
    * @param string $rule
    *   The string rule to parse.
    * @retval array
+   * @return array
    *   The rule as an array.
    */
   public static function parseRule($perm, $rule) {
@@ -392,6 +396,7 @@ class ACL {
    * Get the rules array for this ACL.
    *
    * @retval array
+   * @return array
    *   An array of associative arrays of rules.
    */
   public function rules() {
@@ -496,6 +501,7 @@ class ACL {
    * at all.
    *
    * @retval boolean
+   * @return boolean
    *   TRUE if this is private (non-public), FALSE if
    *   any permissions are granted via this ACL.
    */
@@ -544,6 +550,7 @@ class ACL {
    * a pretty string.
    *
    * @retval string
+   * @return string
    *   The ACL represented as a string.
    */
   public function __toString() {

src/HPCloud/Storage/ObjectStorage/Container.php

@@ -110,6 +110,7 @@ class Container implements \Countable, \IteratorAggregate {
    * @param string $prefix
    *   A prefix for the metadata headers.
    * @retval array
+   * @return 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
@@ -143,6 +144,7 @@ class Container implements \Countable, \IteratorAggregate {
    * @param string $oname
    *   The name of the object.
    * @retval string
+   * @return string
    *   The URL to the object. Characters that need escaping will be escaped,
    *   while slash characters are not. Thus, the URL will look pathy.
    */
@@ -179,6 +181,7 @@ class Container implements \Countable, \IteratorAggregate {
    * @param string $prefix
    *   The prefix on metadata headers.
    * @retval array
+   * @return array
    *   An associative array of name/value attribute pairs.
    */
   public static function extractHeaderAttributes($headers, $prefix = NULL) {
@@ -252,7 +255,8 @@ class Container implements \Countable, \IteratorAggregate {
    * @param string $url
    *   The base URL. The container name is automatically appended to
    *   this at construction time.
-   * @retval Container
+   * @retval HPCloud::Storage::ObjectStorage::Container
+   * @return \HPCloud\Storage\ObjectStorage\Container
    *   The Container object, initialized and ready for use.
    */
   public static function newFromResponse($name, $response, $token, $url) {
@@ -348,6 +352,7 @@ class Container implements \Countable, \IteratorAggregate {
    * Get the name of this container.
    *
    * @retval string
+   * @return string
    *   The name of the container.
    */
   public function name() {
@@ -358,6 +363,7 @@ class Container implements \Countable, \IteratorAggregate {
    * Get the number of bytes in this container.
    *
    * @retval int
+   * @return int
    *   The number of bytes in this container.
    */
   public function bytes() {
@@ -383,6 +389,7 @@ class Container implements \Countable, \IteratorAggregate {
    * directly does.
    *
    * @retval array
+   * @return array
    *   An array of metadata name/value pairs.
    */
   public function metadata() {
@@ -436,6 +443,7 @@ class Container implements \Countable, \IteratorAggregate {
    * @endcode
    *
    * @retval int
+   * @return int
    *   The number of items in this container.
    */
   public function count() {
@@ -458,6 +466,7 @@ class Container implements \Countable, \IteratorAggregate {
    *   An optional file argument that, if set, will be treated as the
    *   contents of the object.
    * @retval boolean
+   * @return boolean
    *   TRUE if the object was saved.
    * @throws HPCloud::Transport::LengthRequiredException
    *   if the Content-Length could not be determined and chunked
@@ -577,6 +586,7 @@ class Container implements \Countable, \IteratorAggregate {
    *   The object to update.
    *
    * @retval boolean
+   * @return boolean
    *   TRUE if the metadata was updated.
    *
    * @throws HPCloud::Transport::FileNotFoundException
@@ -695,7 +705,8 @@ class Container implements \Countable, \IteratorAggregate {
    *   If this is TRUE (the default), then SSL will always be
    *   used. If this is FALSE, then CDN-based fetching will
    *   use non-SSL, which is faster.
-   * @retval \HPCloud\Storage\ObjectStorage\RemoteObject
+   * @retval HPCloud::Storage::ObjectStorage::RemoteObject
+   * @return \HPCloud\Storage\ObjectStorage\RemoteObject
    *   A remote object with the content already stored locally.
    */
   public function object($name, $requireSSL = TRUE) {
@@ -759,7 +770,8 @@ class Container implements \Countable, \IteratorAggregate {
    *
    * @param string $name
    *   The name of the object to fetch.
-   * @retval \HPCloud\Storage\ObjectStorage\RemoteObject
+   * @retval HPCloud::Storage::ObjectStorage::RemoteObject
+   * @return \HPCloud\Storage\ObjectStorage\RemoteObject
    *   A remote object ready for use.
    */
   public function proxyObject($name) {
@@ -830,6 +842,7 @@ class Container implements \Countable, \IteratorAggregate {
    *   The name of the object to start with. The query will begin with
    *   the next object AFTER this one.
    * @retval array
+   * @return array
    *   List of RemoteObject or Subdir instances.
    */
   public function objects($limit = NULL, $marker = NULL) {
@@ -891,6 +904,7 @@ class Container implements \Countable, \IteratorAggregate {
    *   The name of the object to start with. The query will begin with
    *   the next object AFTER this one.
    * @retval array
+   * @return array
    *   List of RemoteObject or Subdir instances.
    */
   public function objectsWithPrefix($prefix, $delimiter = '/', $limit = NULL, $marker = NULL) {
@@ -956,6 +970,7 @@ class Container implements \Countable, \IteratorAggregate {
    * ObjectStorage::createContainer()) will be accessible by this URL.
    *
    * @retval string
+   * @return string
    *   The URL.
    */
   public function url() {
@@ -981,6 +996,7 @@ class Container implements \Countable, \IteratorAggregate {
    *
    * @todo Determine how to get the ACL from JSON data.
    * @retval \HPCloud\Storage\ObjectStorage\ACL
+   * @return HPCloud::Storage::ObjectStorage::ACL
    *   An ACL, or NULL if the ACL could not be retrieved.
    */
   public function acl() {
@@ -1117,6 +1133,7 @@ class Container implements \Countable, \IteratorAggregate {
    * @param string $name
    *   The name of the object to remove.
    * @retval boolean
+   * @return boolean
    *   TRUE if the file was deleted, FALSE if no such file is found.
    */
   public function delete($name) {

src/HPCloud/Storage/ObjectStorage/Object.php

@@ -164,6 +164,7 @@ class Object {
    * This returns an associative array of all metadata for this object.
    *
    * @retval array
+   * @return array
    *   An associative array of metadata. This may be empty.
    */
   public function metadata() {
@@ -200,6 +201,7 @@ class Object {
    * using setName(), this will return the latest (overwritten) name.
    *
    * @retval string
+   * @return string
    *   The name of the object.
    */
   public function name() {
@@ -248,6 +250,7 @@ class Object {
    * This returns the currently set content type.
    *
    * @retval string
+   * @return string
    *   The content type, including any additional options.
    */
   public function contentType() {
@@ -306,6 +309,7 @@ class Object {
    * returns the entire contents of an object.
    *
    * @retval string
+   * @return string
    *   The content of the file.
    */
   public function content() {
@@ -323,7 +327,8 @@ class Object {
    * When extending this class, you should make sure to calculate the
    * content length appropriately.
    *
-   * return int
+   * @retval int
+   * @return int
    *   The length of the content, in bytes.
    */
   public function contentLength() {
@@ -341,6 +346,7 @@ class Object {
    * the entire object's content (but not the metadata or name).
    *
    * @retval string
+   * @return string
    *   An MD5 value as a string of 32 hex digits (0-9a-f).
    */
   public function eTag() {
@@ -383,6 +389,7 @@ class Object {
    * See setEncoding() for more information.
    *
    * @retval string
+   * @return string
    *   The encoding type.
    */
   public function encoding() {
@@ -426,6 +433,7 @@ class Object {
    * See setDisposition() for discussion.
    *
    * @retval string
+   * @return string
    *   The disposition string, or NULL if none is set.
    */
   public function disposition() {
@@ -524,6 +532,7 @@ class Object {
    * if this returns TRUE, contentLength() is ignored.
    *
    * @retval boolean
+   * @return boolean
    *   TRUE to recommend chunked transfer, FALSE otherwise.
    */
   public function isChunked() {

src/HPCloud/Storage/ObjectStorage/RemoteObject.php

@@ -210,6 +210,7 @@ class RemoteObject extends Object {
    *   (b) it mirrors non-CDN behavior. This can be turned off by setting
    *   $useSSL to FALSE.
    * @retval string
+   * @return string
    *   A URL to the object. The following considerations apply:
    *   - If the container is public, this URL can be loaded without
    *     authentication. You can, for example, pass the URL to a browser
@@ -281,6 +282,7 @@ class RemoteObject extends Object {
    * were sent from the server.
    *
    * @retval array
+   * @return array
    *   An associative array of header names and values.
    */
   public function headers() {
@@ -363,6 +365,7 @@ class RemoteObject extends Object {
    * Be wary of using this method with large files.
    *
    * @retval string
+   * @return string
    *   The contents of the file as a string.
    * @throws \HPCloud\Transport\FileNotFoundException
    *   when the requested content cannot be located on the remote
@@ -429,6 +432,7 @@ class RemoteObject extends Object {
    *   and the content will be refreshed from the server. Any
    *   local changes to the object will be discarded.
    * @retval resource
+   * @return resource
    *   A handle to the stream, which is already opened and positioned at
    *   the beginning of the stream.
    */
@@ -497,6 +501,7 @@ class RemoteObject extends Object {
    * its contents, not whether anything is actually cached.
    *
    * @retval boolean
+   * @return boolean
    *   TRUE if caching is enabled, FALSE otherwise.
    */
   public function isCaching() {
@@ -544,6 +549,7 @@ class RemoteObject extends Object {
    * supplied ETag hash.
    *
    * @retval boolean
+   * @return boolean
    *   TRUE if this is verifying, FALSE otherwise.
    */
   public function isVerifyingContent() {
@@ -622,7 +628,8 @@ 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.
-   * @retval \HPCloud\Transport\Response
+   * @retval HPCloud::Transport::Response
+   * @return \HPCloud\Transport\Response
    *   containing the object metadata and (depending on the
    *   $fetchContent flag) optionally the data.
    */

src/HPCloud/Storage/ObjectStorage/StreamWrapper.php

@@ -407,6 +407,7 @@ class StreamWrapper {
    * @param int $options
    *   Unused.
    * @retval boolean
+   * @return boolean
    *   TRUE if the directory is opened, FALSE otherwise.
    */
   public function dir_opendir($path, $options) {
@@ -462,6 +463,7 @@ class StreamWrapper {
    * @endcode
    *
    * @retval string
+   * @return string
    *   The name of the resource or FALSE when the directory has no more
    *   entries.
    */
@@ -562,6 +564,7 @@ class StreamWrapper {
    * @param string $path_to
    *   A swift URL to another path.
    * @retval boolean
+   * @return boolean
    *   TRUE on success, FALSE otherwise.
    */
   public function rename($path_from, $path_to) {
@@ -609,6 +612,7 @@ class StreamWrapper {
    * side effects.
    *
    * @retval resource
+   * @return resource
    *   this returns the underlying stream.
    */
   public function stream_cast($cast_as) {
@@ -662,6 +666,7 @@ class StreamWrapper {
    * See stream_seek().
    *
    * @retval boolean
+   * @return boolean
    *   TRUE if it has reached the end, FALSE otherwise.
    */
   public function stream_eof() {
@@ -969,6 +974,7 @@ class StreamWrapper {
    * @param int $count
    *   The number of bytes to read (usually 8192).
    * @retval string
+   * @return string
    *   The data read.
    */
   public function stream_read($count) {
@@ -1034,6 +1040,7 @@ class StreamWrapper {
    * etc.) through HPCloud::Bootstrap::setConfiguration().
    *
    * @retval array
+   * @return array
    *   The stats array.
    */
   public function stream_stat() {
@@ -1052,6 +1059,7 @@ class StreamWrapper {
    * See ftell() and fseek().
    *
    * @retval int
+   * @return int
    *   The current position in the stream.
    */
   public function stream_tell() {
@@ -1068,6 +1076,7 @@ class StreamWrapper {
    * @param string $data
    *   Data to write to the stream.
    * @retval int
+   * @return int
    *   The number of bytes written. 0 indicates and error.
    */
   public function stream_write($data) {
@@ -1094,6 +1103,7 @@ class StreamWrapper {
    * @param string $path
    *   The URL.
    * @retval boolean
+   * @return boolean
    *   TRUE if the file was deleted, FALSE otherwise.
    */
   public function unlink($path) {
@@ -1409,6 +1419,7 @@ class StreamWrapper {
    * @param mixed $default
    *   The default value to return if no config param was found.
    * @retval mixed
+   * @return mixed
    *   The discovered result, or $default if specified, or NULL if
    *   no $default is specified.
    */
@@ -1455,6 +1466,7 @@ class StreamWrapper {
    * @param string $url
    *   A Swift URL.
    * @retval array
+   * @return array
    *   An array as documented in parse_url().
    */
   protected function parseUrl($url) {

src/HPCloud/Storage/ObjectStorage/StreamWrapperFS.php

@@ -148,7 +148,8 @@ class StreamWrapperFS extends StreamWrapper {
    * 
    * @param  string $path
    *   The directory path to test.
-   * @retval bool
+   * @retval boolean
+   * @return boolean
    *   TRUE if the directory prefix exists and FALSE otherwise.
    */
   protected function testDirectoryExists($path) {

src/HPCloud/Storage/ObjectStorage/Subdir.php

@@ -61,6 +61,7 @@ class Subdir {
    * The path is delimited using the string returned by delimiter().
    *
    * @retval string
+   * @return string
    *   The path.
    */
   public function path() {
@@ -70,6 +71,7 @@ class Subdir {
    * Get the delimiter used by the server.
    *
    * @retval string
+   * @return string
    *   The value used as a delimiter.
    */
   public function delimiter() {

src/HPCloud/Transport.php

@@ -72,6 +72,7 @@ class Transport {
    * @endcode
    *
    * @retval HPCloud::Transport::Transporter
+   * @return \HPCloud\Transport\Transporter
    *   An initialized transporter.
    */
   public static function instance() {

src/HPCloud/Transport/CURLTransport.php

@@ -278,6 +278,7 @@ class CURLTransport implements Transporter {
    * @param resource $handle
    *   A CURL handle from curl_init().
    * @retval boolean
+   * @return boolean
    *   Returns a boolean value indicating whether or not CURL could process the
    *   request.
    */
@@ -322,6 +323,7 @@ class CURLTransport implements Transporter {
    * @param resource $file
    *   A file pointer to the file that has the headers.
    * @retval array
+   * @return array
    *   An array of headers, one header per line.
    */
   protected function fetchHeaders($file) {

src/HPCloud/Transport/PHPStreamTransport.php

@@ -207,6 +207,7 @@ class PHPStreamTransport implements Transporter {
    * @param array $headers
    *   An associative array of header names to header values.
    * @retval string
+   * @return string
    *   A string containing formatted headers.
    */
   protected function smashHeaders($headers) {

src/HPCloud/Transport/Response.php

@@ -143,6 +143,7 @@ class Response {
    * (they are one and the same).
    *
    * @retval resource
+   * @return resource
    *   A file handle.
    */
   public function file() {
@@ -162,6 +163,7 @@ class Response {
    * entire content in a string.
    *
    * @retval string
+   * @return string
    *   The contents of the response body.
    */
   public function content() {
@@ -203,6 +205,7 @@ class Response {
    * data.
    *
    * @retval array
+   * @return array
    *   An associative array of metadata about the
    *   transaction resulting in this response.
    */
@@ -219,6 +222,7 @@ class Response {
    *   An optional default value.
    *
    * @retval mixed
+   * @return mixed
    *   The value, if found, or the default, is specified, or NULL.
    */
   public function header($name, $default = NULL) {
@@ -237,8 +241,9 @@ class Response {
    *
    * These are available even if the stream has been closed.
    *
-   * @retval
+   * @retval array
-   *   array The array of headers.
+   * @return array
+   *   The array of headers.
    */
   public function headers() {
     return $this->headers;
@@ -266,6 +271,7 @@ class Response {
    * appear in a Response object.
    *
    * @retval int
+   * @return int
    *   The HTTP code, e.g. 200 or 202.
    */
   public function status() {
@@ -279,6 +285,7 @@ class Response {
    * recommendations. e.g. 200 returns 'OK'.
    *
    * @retval string
+   * @return string
    *  A server-generated status message.
    */
   public function statusMessage() {
@@ -291,6 +298,7 @@ class Response {
    * Example: HTTP/1.1
    *
    * @retval string
+   * @return string
    *   The protocol name and version.
    */
   public function protocol() {
@@ -308,6 +316,7 @@ class Response {
    *   An indexed array of headers, as returned by the PHP stream
    *   library.
    * @retval array
+   * @return array
    *   An associative array of header name/value pairs.
    */
   protected function parseHeaders($headerArray) {