diff --git a/lib/public/contacts.php b/lib/public/contacts.php
index 6842f40f1b..ca0b15b2c7 100644
--- a/lib/public/contacts.php
+++ b/lib/public/contacts.php
@@ -41,10 +41,10 @@ namespace OC {
 		public function getDisplayName();
 
 		/**
-		 * @param $pattern
-		 * @param $searchProperties
-		 * @param $options
-		 * @return mixed
+		 * @param string $pattern which should match within the $searchProperties
+		 * @param array $searchProperties defines the properties within the query pattern should match
+		 * @param array $options - for future use. One should always have options!
+		 * @return array of contacts which are arrays of key-value-pairs
 		 */
 		public function search($pattern, $searchProperties, $options);
 //			// dummy results
@@ -54,8 +54,8 @@ namespace OC {
 //			);
 
 		/**
-		 * @param $properties
-		 * @return mixed
+		 * @param array $properties this array if key-value-pairs defines a contact
+		 * @return array representing the contact just created or updated
 		 */
 		public function createOrUpdate($properties);
 //			// dummy
@@ -70,8 +70,8 @@ namespace OC {
 		public function getPermissions();
 
 		/**
-		 * @param $id
-		 * @return mixed
+		 * @param object $id the unique identifier to a contact
+		 * @return bool successful or not
 		 */
 		public function delete($id);
 	}