Fix phpdoc comments for SimpleSAML_Metadata_MetaDataStorageHandler.

lib/SimpleSAML/Metadata/MetaDataStorageHandler.php

@@ -11,8 +11,10 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 
 	/**
 	 * This static variable contains a reference to the current
-	 * instance of the metadata handler. This variable will be NULL if
+	 * instance of the metadata handler. This variable will be null if
 	 * we haven't instantiated a metadata handler yet.
+	 *
+	 * @var SimpleSAML_Metadata_MetaDataStorageHandler
 	 */
 	private static $metadataHandler = NULL;
 
@@ -20,6 +22,8 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	/**
 	 * This is a list of all the metadata sources we have in our metadata
 	 * chain. When we need metadata, we will look through this chain from start to end.
+	 *
+	 * @var array
 	 */
 	private $sources;
 
@@ -29,7 +33,7 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	 * The metadata handler will be instantiated if this is the first call
 	 * to this fuunction.
 	 *
-	 * @return The current metadata handler instance.
+	 * @return SimpleSAML_Metadata_MetaDataStorageHandler The current metadata handler instance.
 	 */
 	public static function getMetadataHandler() {
 		if(self::$metadataHandler === NULL) {
@@ -69,9 +73,9 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	/**
 	 * This function is used to generate some metadata elements automatically.
 	 *
-	 * @param $property  The metadata property which should be autogenerated.
-	 * @param $set  The set we the property comes from.
-	 * @return The autogenerated metadata property.
+	 * @param string $property The metadata property which should be autogenerated.
+	 * @param string  $set The set we the property comes from.
+	 * @return string The autogenerated metadata property.
 	 */
 	public function getGenerated($property, $set) {
 
@@ -126,8 +130,8 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	 * This function lists all known metadata in the given set. It is returned as an associative array
 	 * where the key is the entity id.
 	 *
-	 * @param $set  The set we want to list metadata from.
-	 * @return An associative array with the metadata from from the given set.
+	 * @param string $set The set we want to list metadata from.
+	 * @return array An associative array with the metadata from from the given set.
 	 */
 	public function getList($set = 'saml20-idp-remote') {
 
@@ -166,8 +170,8 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	 * This function retrieves metadata for the current entity based on the hostname/path the request
 	 * was directed to. It will throw an exception if it is unable to locate the metadata.
 	 *
-	 * @param $set  The set we want metadata from.
-	 * @return An associative array with the metadata.
+	 * @param string $set The set we want metadata from.
+	 * @return array An associative array with the metadata.
 	 */
 	public function getMetaDataCurrent($set) {
 		return $this->getMetaData(NULL, $set);
@@ -178,9 +182,9 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	 * This function locates the current entity id based on the hostname/path combination the user accessed.
 	 * It will throw an exception if it is unable to locate the entity id.
 	 *
-	 * @param $set  The set we look for the entity id in.
-	 * @param $type Do you want to return the metaindex or the entityID. [entityid|metaindex]
-	 * @return The entity id which is associated with the current hostname/path combination.
+	 * @param string $set The set we look for the entity id in.
+	 * @param string $type Do you want to return the metaindex or the entityID. [entityid|metaindex]
+	 * @return string The entity id which is associated with the current hostname/path combination.
 	 */
 	public function getMetaDataCurrentEntityID($set, $type = 'entityid') {
 
@@ -230,9 +234,9 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	 * This method will call getPreferredEntityIdFromCIDRhint() on all of the
 	 * sources.
 	 *
-	 * @param $set  Which set of metadata we are looking it up in.
-	 * @param $ip	IP address
-	 * @return The entity id of a entity which have a CIDR hint where the provided
+	 * @param string $set Which set of metadata we are looking it up in.
+	 * @param string $ip IP address
+	 * @return string The entity id of a entity which have a CIDR hint where the provided
 	 * 		IP address match.
 	 */
 	public function getPreferredEntityIdFromCIDRhint($set, $ip) {
@@ -252,9 +256,12 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	 * This function looks up the metadata for the given entity id in the given set. It will throw an
 	 * exception if it is unable to locate the metadata.
 	 *
-	 * @param $index  The entity id we are looking up. This parameter may be NULL, in which case we look up
-	 *                   the current entity id based on the current hostname/path.
-	 * @param $set  The set of metadata we are looking up the entity id in.
+	 * @param string $index The entity id we are looking up. This parameter may be NULL, in which case we look up
+	 * the current entity id based on the current hostname/path.
+	 * @param string $set The set of metadata we are looking up the entity id in.
+	 * @return array The metadata array describing the specified entity.
+	 * @throws Exception If metadata for the specified entity is expired.
+	 * @throws SimpleSAML_Error_MetadataNotFound If no metadata for the entity specified can be found.
 	 */
 	public function getMetaData($index, $set) {
 
@@ -295,9 +302,10 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 	 *
 	 * This function will throw an exception if it is unable to locate the metadata.
 	 *
-	 * @param string $entityId  The entity ID we are looking up.
-	 * @param string $set  The metadata set we are searching.
-	 * @return SimpleSAML_Configuration  The configuration object representing the metadata.
+	 * @param string $entityId The entity ID we are looking up.
+	 * @param string $set The metadata set we are searching.
+	 * @return SimpleSAML_Configuration The configuration object representing the metadata.
+	 * @throws SimpleSAML_Error_MetadataNotFound If no metadata for the entity specified can be found.
 	 */
 	public function getMetaDataConfig($entityId, $set) {
 		assert('is_string($entityId)');
@@ -307,6 +315,16 @@ class SimpleSAML_Metadata_MetaDataStorageHandler {
 		return SimpleSAML_Configuration::loadFromArray($metadata, $set . '/' . var_export($entityId, TRUE));
 	}
 
+
+	/**
+	 * Search for an entity's metadata, given the SHA1 digest of its entity ID.
+	 *
+	 * @param string $sha1 The SHA1 digest of the entity ID.
+	 * @param string $set The metadata set we are searching.
+	 *
+	 * @return null|SimpleSAML_Configuration The metadata corresponding to the entity, or null if the entity cannot be
+	 * found.
+	 */
 	public function	getMetaDataConfigForSha1($sha1, $set) {
 		assert('is_string($sha1)');
 		assert('is_string($set)');