Added phpdoc comments

Author: Matt Oakes

lastfmapi/api/album.php

@@ -1,19 +1,48 @@
 <?php
-
-class lastfmApiAlbum extends lastfmApiBase {
-	public $info;
-	public $tags;
+/**
+ * File that stores api calls for album api calls
+ * @package album
+ */
+/**
+ * Allows access to the api requests relating to albums
+ * @package album
+ */
+class lastfmApiAlbum extends lastfmApi {
+	/**
+	 * Stores the config values set in the call
+	 * @access public
+	 * @var array
+	 */
 	public $config;
-	
+	/**
+	 * Stores the auth variables used in all api calls
+	 * @access private
+	 * @var array
+	 */
 	private $auth;
+	/**
+	 * States if the user has full authentication to use api requests that modify data
+	 * @access private
+	 * @var boolean
+	 */
 	private $fullAuth;
 
+	/**
+	 * @param array $auth Passes the authentication variables
+	 * @param array $fullAuth A boolean value stating if the user has full authentication or not
+	 * @param array $config An array of config variables related to caching and other features
+	 */
 	function __construct($auth, $fullAuth, $config) {
 		$this->auth = $auth;
 		$this->fullAuth = $fullAuth;
 		$this->config = $config;
 	}
 
+	/**
+	 * Tag an album using a list of user supplied tags. (Requires full auth)
+	 * @param array $methodVars An array with the following required values: <i>album</i>, <i>artist</i>, <i>tags</i>
+	 * @return boolean
+	 */
 	public function addTags($methodVars) {
 		// Only allow full authed calls
 		if ( $this->fullAuth == TRUE ) {
@@ -67,6 +96,11 @@ public function addTags($methodVars) {
 		}
 	}
 
+	/**
+	 * Get the metadata for an album on Last.fm using the album name or a musicbrainz id
+	 * @param array $methodVars An array with the following required values: <i>album</i> and optional values: <i>artist</i>, <i>mbid</i>
+	 * @return array
+	 */
 	public function getInfo($methodVars) {
 		// Set the call variables
 		$vars = array(
@@ -76,33 +110,39 @@ public function getInfo($methodVars) {
 			'artist' => @$methodVars['artist'],
 			'mbid' => @$methodVars['mbid']
 		);
+		$info = array();
 
 		if ( $call = $this->apiGetCall($vars) ) {
-			$this->info['name'] = (string) $call->album->name;
-			$this->info['artist'] = (string) $call->album->artist;
-			$this->info['lastfmid'] = (string) $call->album->id;
-			$this->info['mbid'] = (string) $call->album->mbid;
-			$this->info['url'] = (string) $call->album->url;
-			$this->info['releasedate'] = strtotime(trim((string) $call->album->releasedate));
-			$this->info['image']['small'] = (string) $call->album->image;
-			$this->info['image']['medium'] = (string) $call->album->image[1];
-			$this->info['image']['large'] = (string) $call->album->image[2];
-			$this->info['listeners'] = (string) $call->album->listeners;
-			$this->info['playcount'] = (string) $call->album->playcount;
+			$info['name'] = (string) $call->album->name;
+			$info['artist'] = (string) $call->album->artist;
+			$info['lastfmid'] = (string) $call->album->id;
+			$info['mbid'] = (string) $call->album->mbid;
+			$info['url'] = (string) $call->album->url;
+			$info['releasedate'] = strtotime(trim((string) $call->album->releasedate));
+			$info['image']['small'] = (string) $call->album->image;
+			$info['image']['medium'] = (string) $call->album->image[1];
+			$info['image']['large'] = (string) $call->album->image[2];
+			$info['listeners'] = (string) $call->album->listeners;
+			$info['playcount'] = (string) $call->album->playcount;
 			$i = 0;
 			foreach ( $call->album->toptags->tag as $tags ) {
-				$this->info['toptags'][$i]['name'] = (string) $tags->name;
-				$this->info['toptags'][$i]['url'] = (string) $tags->url;
+				$info['toptags'][$i]['name'] = (string) $tags->name;
+				$info['toptags'][$i]['url'] = (string) $tags->url;
 				$i++;
 			}
 
-			return $this->info;
+			return $info;
 		}
 		else {
 			return FALSE;
 		}
 	}
 
+	/**
+	 * Get the tags applied by an individual user to an album on Last.fm
+	 * @param array $methodVars An array with the following required values: <i>album</i>, <i>artist</i>
+	 * @return array
+	 */
 	public function getTags($methodVars) {
 		// Only allow full authed calls
 		if ( $this->fullAuth == TRUE ) {
@@ -119,18 +159,19 @@ public function getTags($methodVars) {
 				// Generate a call signiture
 				$sig = $this->apiSig($this->auth->secret, $vars);
 				$vars['api_sig'] = $sig;
+				$tags = array();
 
 				// Make the call
 				if ( $call = $this->apiGetCall($vars) ) {
 					if ( count($call->tags->tag) > 0 ) {
 						$i = 0;
 						foreach ( $call->tags->tag as $tag ) {
-							$this->tags[$i]['name'] = (string) $tag->name;
-							$this->tags[$i]['url'] = (string) $tag->url;
+							$tags[$i]['name'] = (string) $tag->name;
+							$tags[$i]['url'] = (string) $tag->url;
 							$i++;
 						}
 
-						return $this->tags;
+						return $tags;
 					}
 					else {
 						$this->handleError(90, 'User has no tags for this artist');
@@ -154,6 +195,11 @@ public function getTags($methodVars) {
 		}
 	}
 
+	/**
+	 * Remove a user's tag from an album. (Requires full auth)
+	 * @param array $methodVars An array with the following required values: <i>album</i>, <i>artist</i>, <i>tag</i>
+	 * @return boolean
+	 */
 	public function removeTag($methodVars) {
 		// Only allow full authed calls
 		if ( $this->fullAuth == TRUE ) {
@@ -193,6 +239,11 @@ public function removeTag($methodVars) {
 		}
 	}
 
+	/**
+	 * Search for an album by name. Returns album matches sorted by relevance
+	 * @param array $methodVars An array with the following required values: <i>album</i>
+	 * @return array
+	 */
 	public function search($methodVars) {
 		// Check for required variables
 		if ( !empty($methodVars['album']) ) {
@@ -207,27 +258,28 @@ public function search($methodVars) {
 			if ( !empty($methodVars['page']) ) {
 				$vars['page'] = $methodVars['page'];
 			}
+			$searchresults = array();
 
 			if ( $call = $this->apiGetCall($vars) ) {
 				$opensearch = $call->results->children('http://a9.com/-/spec/opensearch/1.1/');
 				if ( $opensearch->totalResults > 0 ) {
-					$this->searchResults['totalResults'] = (string) $opensearch->totalResults;
-					$this->searchResults['startIndex'] = (string) $opensearch->startIndex;
-					$this->searchResults['itemsPerPage'] = (string) $opensearch->itemsPerPage;
+					$searchresults['totalResults'] = (string) $opensearch->totalResults;
+					$searchresults['startIndex'] = (string) $opensearch->startIndex;
+					$searchresults['itemsPerPage'] = (string) $opensearch->itemsPerPage;
 					$i = 0;
 					foreach ( $call->results->albummatches->album as $album ) {
-						$this->searchResults['results'][$i]['name'] = (string) $album->name;
-						$this->searchResults['results'][$i]['artist'] = (string) $album->artist;
-						$this->searchResults['results'][$i]['id'] = (string) $album->id;
-						$this->searchResults['results'][$i]['url'] = (string) $album->url;
-						$this->searchResults['results'][$i]['streamable'] = (string) $album->streamable;
-						$this->searchResults['results'][$i]['image']['small'] = (string) $album->image[0];
-						$this->searchResults['results'][$i]['image']['medium'] = (string) $album->image[1];
-						$this->searchResults['results'][$i]['image']['large'] = (string) $album->image[2];
+						$searchresults['results'][$i]['name'] = (string) $album->name;
+						$searchresults['results'][$i]['artist'] = (string) $album->artist;
+						$searchresults['results'][$i]['id'] = (string) $album->id;
+						$searchresults['results'][$i]['url'] = (string) $album->url;
+						$searchresults['results'][$i]['streamable'] = (string) $album->streamable;
+						$searchresults['results'][$i]['image']['small'] = (string) $album->image[0];
+						$searchresults['results'][$i]['image']['medium'] = (string) $album->image[1];
+						$searchresults['results'][$i]['image']['large'] = (string) $album->image[2];
 						$i++;
 					}
 
-					return $this->searchResults;
+					return $searchresults;
 				}
 				else {
 					// No tagsare found