Add missing phpdoc

9 files changed, 208 insertions, 26 deletions

diff --git a/lib/Db/CredentialMapper.php b/lib/Db/CredentialMapper.php
index bfcd146f..32303ca8 100644
--- a/lib/Db/CredentialMapper.php
+++ b/lib/Db/CredentialMapper.php
@@ -36,8 +36,10 @@ class CredentialMapper extends Mapper {
 
 
 	/**
+	 * Obtains the credentials by vault id (not guid)
 	 * @throws \OCP\AppFramework\Db\DoesNotExistException if not found
 	 * @throws \OCP\AppFramework\Db\MultipleObjectsReturnedException if more than one result
+	 * @return Vault[]
 	 */
 	public function getCredentialsByVaultId($vault_id, $user_id) {
 		$sql = 'SELECT * FROM `*PREFIX*passman_credentials` ' .
@@ -46,9 +48,10 @@ class CredentialMapper extends Mapper {
 	}
 
 	/**
+	 * Get a random credentail from a vault
 	 * @param $vault_id
 	 * @param $user_id
-	 * @return Credential[]
+	 * @return Credential
 	 */
 	public function getRandomCredentialByVaultId($vault_id, $user_id) {
 		$sql = 'SELECT * FROM `*PREFIX*passman_credentials` ' .
@@ -60,6 +63,7 @@ class CredentialMapper extends Mapper {
 	}
 
 	/**
+	 * Get expired credentials
 	 * @param $timestamp
 	 * @return Credential[]
 	 */
@@ -70,6 +74,8 @@ class CredentialMapper extends Mapper {
 	}
 
     /**
+	 * Get an credential by id.
+	 * Optional user id
      * @param $credential_id
      * @param null $user_id
      * @return Credential
@@ -87,6 +93,7 @@ class CredentialMapper extends Mapper {
 	}
 
 	/**
+	 * Get credential label by id
 	 * @param $credential_id
 	 * @return Credential
 	 */
@@ -97,6 +104,7 @@ class CredentialMapper extends Mapper {
 	}
 
 	/**
+	 * Save credential to the database.
 	 * @param $raw_credential
 	 * @return Credential
 	 */
@@ -128,6 +136,7 @@ class CredentialMapper extends Mapper {
 	}
 
 	/**
+	 * Update a credential
 	 * @param $raw_credential array An array containing all the credential fields
 	 * @return Credential The updated credential
 	 */
diff --git a/lib/Db/CredentialRevisionMapper.php b/lib/Db/CredentialRevisionMapper.php
index 24d06141..a22f5d1b 100644
--- a/lib/Db/CredentialRevisionMapper.php
+++ b/lib/Db/CredentialRevisionMapper.php
@@ -37,8 +37,10 @@ class CredentialRevisionMapper extends Mapper {
 
 
 	/**
+	 * Get revisions from a credential
 	 * @throws \OCP\AppFramework\Db\DoesNotExistException if not found
 	 * @throws \OCP\AppFramework\Db\MultipleObjectsReturnedException if more than one result
+	 * @return CredentialRevision[]
 	 */
 	public function getRevisions($credential_id, $user_id = null) {
 		$sql = 'SELECT * FROM `*PREFIX*passman_revisions` ' .
@@ -68,6 +70,7 @@ class CredentialRevisionMapper extends Mapper {
 	}
 
 	/**
+	 * Create a revision
 	 * @param $credential
 	 * @param $userId
 	 * @param $credential_id
@@ -85,6 +88,13 @@ class CredentialRevisionMapper extends Mapper {
 		return $this->insert($revision);
 	}
 
+
+	/**
+	 * Delete a revision
+	 * @param $revision_id
+	 * @param $user_id
+	 * @return CredentialRevision
+	 */
 	public function deleteRevision($revision_id, $user_id) {
 		$revision = new CredentialRevision();
 		$revision->setId($revision_id);
diff --git a/lib/Db/FileMapper.php b/lib/Db/FileMapper.php
index 103cdeae..d0dd80d9 100644
--- a/lib/Db/FileMapper.php
+++ b/lib/Db/FileMapper.php
@@ -91,6 +91,12 @@ class FileMapper extends Mapper {
 		return $this->insert($file);
 	}
 
+	/**
+	 * Delete a file by file_id and user id
+	 * @param $file_id
+	 * @param $userId
+	 * @return File
+	 */
 	public function deleteFile($file_id, $userId) {
 		$file = new File();
 		$file->setId($file_id);
@@ -98,6 +104,11 @@ class FileMapper extends Mapper {
 		$this->delete($file);
 	}
 
+	/**
+	 * Uodate file
+	 * @param File $file
+	 * @return File
+	 */
 	public function updateFile(File $file) {
 		return $this->update($file);
 	}
diff --git a/lib/Db/VaultMapper.php b/lib/Db/VaultMapper.php
index 6beca01d..071bbd98 100644
--- a/lib/Db/VaultMapper.php
+++ b/lib/Db/VaultMapper.php
@@ -38,7 +38,7 @@ class VaultMapper extends Mapper {
 	/**
 	 * @throws \OCP\AppFramework\Db\DoesNotExistException if not found
 	 * @throws \OCP\AppFramework\Db\MultipleObjectsReturnedException if more than one result
-	 * @return Vault
+	 * @return Vault[]
 	 */
 	public function find($vault_id, $user_id) {
 		$sql = 'SELECT * FROM `*PREFIX*passman_vaults` ' .
@@ -85,6 +85,11 @@ class VaultMapper extends Mapper {
 		return parent::insert($vault);
 	}
 
+	/**
+	 * Update last access time of a vault
+	 * @param $vault_id
+	 * @param $user_id
+	 */
 	public function setLastAccess($vault_id, $user_id){
 		$vault = new Vault();
 		$vault->setId($vault_id);
@@ -93,10 +98,20 @@ class VaultMapper extends Mapper {
 		$this->update($vault);
 	}
 
+	/**
+	 * Update vault
+	 * @param Vault $vault
+	 */
 	public function updateVault(Vault $vault){
 		$this->update($vault);
 	}
 
+	/**
+	 * Update the sharing key's
+	 * @param $vault_id
+	 * @param $privateKey
+	 * @param $publicKey
+	 */
 	public function updateSharingKeys($vault_id, $privateKey, $publicKey){
 		$vault = new Vault();
 		$vault->setId($vault_id);
diff --git a/lib/Service/ActivityService.php b/lib/Service/ActivityService.php
index 8f0bdea6..3a10d56a 100644
--- a/lib/Service/ActivityService.php
+++ b/lib/Service/ActivityService.php
@@ -38,28 +38,15 @@ class ActivityService {
 	}
 
 	/**
-	 * @subject = One of these: item_created, item_edited, item_apply_revision
-	 *                          item_deleted, item_recovered, item_destroyed,
-	 *                          item_expired, item_shared
-	 *
-	 *
-	 *
-	 *
-	 * @subjectParams =  Subject     | Subject params
-	 *                  item_created = array($itemName,$user)
-	 *                  item_edited = array($itemName,$user)
-	 *                  item_apply_revision = array($itemName,$user,$revision);
-	 *                  item_deleted = array($itemName,$user)
-	 *                  item_recovered = array($itemName,$user)
-	 *                  item_destroyed = array($itemName,$user)
-	 *                  item_expired = array($itemName)
-	 *                  item_shared = array($itemName)
-	 * @message = Custom message (not needed)
-	 * @messageParams = Message params (not needed)
-	 * @link = will be -> <ownCloud>/apps/activity/$link
-	 * @user = Target user
-	 * @type = Can be passman_password or passman_password_shared
-	 * @priority = Int -> [10,20,30,40,50]
+	 * Create a new activity
+	 * @param $subject string Subject of the activity
+	 * @param $subjectParams array
+	 * @param $message string
+	 * @param $messageParams array
+	 * @param $link string
+	 * @param $user string
+	 * @param $type string
+	 * @return array
 	 */
 	public function add($subject,$subjectParams=array(),
 						$message='',$messageParams=array(),
diff --git a/lib/Service/CredentialRevisionService.php b/lib/Service/CredentialRevisionService.php
index 6ff990d3..06113371 100644
--- a/lib/Service/CredentialRevisionService.php
+++ b/lib/Service/CredentialRevisionService.php
@@ -38,22 +38,53 @@ class CredentialRevisionService {
 		$this->credentialRevisionMapper = $credentialRevisionMapper;
 	}
 
+	/**
+	 * Create a new revision for a credential
+	 * @param $credential
+	 * @param $userId
+	 * @param $credential_id
+	 * @param $edited_by
+	 * @return CredentialRevision
+	 */
 	public function createRevision($credential, $userId, $credential_id, $edited_by) {
 		return $this->credentialRevisionMapper->create($credential, $userId, $credential_id, $edited_by);
 	}
 
+	/**
+	 * Get revisions of a credential
+	 * @param $credential_id
+	 * @param null $user_id
+	 * @return CredentialRevision[]
+	 */
 	public function getRevisions($credential_id, $user_id = null){
 		return $this->credentialRevisionMapper->getRevisions($credential_id, $user_id);
 	}
 
+	/**
+	 *
+	 * @param $credential_id
+	 * @param null $user_id
+	 * @return CredentialRevision
+	 */
 	public function getRevision($credential_id, $user_id = null){
 		return $this->credentialRevisionMapper->getRevision($credential_id, $user_id);
 	}
 
+	/**
+	 * Delete a revision
+	 * @param $revision_id
+	 * @param $user_id
+	 * @return CredentialRevision
+	 */
 	public function deleteRevision($revision_id, $user_id){
 		return $this->credentialRevisionMapper->deleteRevision($revision_id, $user_id);
 	}
 
+	/**
+	 * Update revision
+	 * @param CredentialRevision $credentialRevision
+	 * @return CredentialRevision
+	 */
 	public function updateRevision(CredentialRevision $credentialRevision){
 		return $this->credentialRevisionMapper->update($credentialRevision);
 	}
diff --git a/lib/Service/CredentialService.php b/lib/Service/CredentialService.php
index ee9767f7..bfd56805 100644
--- a/lib/Service/CredentialService.php
+++ b/lib/Service/CredentialService.php
@@ -24,6 +24,7 @@
 namespace OCA\Passman\Service;
 
 use OCA\Passman\Db\Credential;
+use OCA\Passman\Db\CredentialRevision;
 use OCA\Passman\Db\SharingACL;
 use OCA\Passman\Db\SharingACLMapper;
 use OCP\IConfig;
@@ -52,30 +53,69 @@ class CredentialService {
 		return $this->credentialMapper->create($credential);
 	}
 
+	/**
+	 * Update credential
+	 * @param $credential array
+	 * @return Credential
+	 */
 	public function updateCredential($credential) {
 		return $this->credentialMapper->updateCredential($credential);
 	}
-	public function upd($credential) {
+
+	/**
+	 * Update credential
+	 * @param $credential Credential
+	 */
+	public function upd(Credential $credential) {
 		return $this->credentialMapper->upd($credential);
 	}
 
-	public function deleteCredential($credential){
+	/**
+	 * Delete credential
+	 * @param Credential $credential
+	 * @return \OCP\AppFramework\Db\Entity
+	 */
+	public function deleteCredential(Credential $credential){
 		return $this->credentialMapper->deleteCredential($credential);
 	}
 
+	/**
+	 * Get credentials by vault id
+	 * @param $vault_id
+	 * @param $user_id
+	 * @return \OCA\Passman\Db\Vault[]
+	 */
 	public function getCredentialsByVaultId($vault_id, $user_id) {
 		return $this->credentialMapper->getCredentialsByVaultId($vault_id, $user_id);
 	}
 
+	/**
+	 * Get a random credential from given vault
+	 * @param $vault_id
+	 * @param $user_id
+	 * @return mixed
+	 */
 	public function getRandomCredentialByVaultId($vault_id, $user_id) {
 		$credentials = $this->credentialMapper->getRandomCredentialByVaultId($vault_id, $user_id);
 		return array_pop($credentials);
 	}
 
+	/**
+	 * Get expired credentials.
+	 * @param $timestamp
+	 * @return \OCA\Passman\Db\Credential[]
+	 */
 	public function getExpiredCredentials($timestamp) {
 		return $this->credentialMapper->getExpiredCredentials($timestamp);
 	}
 
+	/**
+	 * Get a single credential.
+	 * @param $credential_id
+	 * @param $user_id
+	 * @return Credential
+	 * @throws DoesNotExistException
+	 */
 	public function getCredentialById($credential_id, $user_id){
         $credential = $this->credentialMapper->getCredentialById($credential_id);
         if ($credential->getUserId() === $user_id){
@@ -89,10 +129,22 @@ class CredentialService {
 
         throw new DoesNotExistException("Did expect one result but found none when executing");
 	}
+
+	/**
+	 * Get credential label by credential id.
+	 * @param $credential_id
+	 * @return Credential
+	 */
 	public function getCredentialLabelById($credential_id){
 		return $this->credentialMapper->getCredentialLabelById($credential_id);
 	}
 
+	/**
+	 * Get credential by guid
+	 * @param $credential_guid
+	 * @param null $user_id
+	 * @return Credential
+	 */
 	public function getCredentialByGUID($credential_guid, $user_id = null){
 	    return $this->credentialMapper->getCredentialByGUID($credential_guid, $user_id);
     }
diff --git a/lib/Service/FileService.php b/lib/Service/FileService.php
index 541e65b1..63da182a 100644
--- a/lib/Service/FileService.php
+++ b/lib/Service/FileService.php
@@ -37,22 +37,51 @@ class FileService {
 		$this->fileMapper = $fileMapper;
 	}
 
+	/**
+	 * Get a single file. This function also returns the file content.
+	 * @param $fileId
+	 * @param null $userId
+	 * @return \OCA\Passman\Db\File
+	 */
 	public function getFile($fileId, $userId = null) {
 		return $this->fileMapper->getFile($fileId, $userId);
 	}
 
+	/**
+	 * Get a single file. This function also returns the file content.
+	 * @param $file_guid
+	 * @param null $userId
+	 * @return \OCA\Passman\Db\File
+	 */
 	public function getFileByGuid($file_guid, $userId = null) {
 		return $this->fileMapper->getFileByGuid($file_guid, $userId);
 	}
 
+	/**
+	 * Upload a new file,
+	 * @param $file array
+	 * @param $userId
+	 * @return \OCA\Passman\Db\File
+	 */
 	public function createFile($file, $userId) {
 		return $this->fileMapper->create($file, $userId);
 	}
 
+	/**
+	 * Delete file
+	 * @param $file_id
+	 * @param $userId
+	 * @return \OCA\Passman\Db\File
+	 */
 	public function deleteFile($file_id, $userId) {
 		return $this->fileMapper->deleteFile($file_id, $userId);
 	}
 
+	/**
+	 * Update file
+	 * @param $file_id
+	 * @return \OCA\Passman\Db\File
+	 */
 	public function updateFile($file_id) {
 		return $this->fileMapper->updateFile($file_id);
 	}
diff --git a/lib/Service/VaultService.php b/lib/Service/VaultService.php
index c648df4e..8e7a8d83 100644
--- a/lib/Service/VaultService.php
+++ b/lib/Service/VaultService.php
@@ -37,32 +37,70 @@ class VaultService {
 		$this->vaultMapper = $vaultMapper;
 	}
 
+	/**
+	 * Get vaults from a user.
+	 * @param $userId
+	 * @return \OCA\Passman\Db\Vault[]
+	 */
 	public function getByUser($userId) {
 		return $this->vaultMapper->findVaultsFromUser($userId);
 	}
 
+	/**
+	 * Get a single vault
+	 * @param $vault_id
+	 * @param $user_id
+	 * @return \OCA\Passman\Db\Vault[]
+	 */
 	public function getById($vault_id, $user_id) {
 		$vault = $this->vaultMapper->find($vault_id, $user_id);
 		return $vault;
 	}
 
+	/**
+	 * Get a single vault.
+	 * @param $vault_guid
+	 * @param $user_id
+	 * @return \OCA\Passman\Db\Vault
+	 */
 	public function getByGuid($vault_guid, $user_id) {
 		$vault = $this->vaultMapper->findByGuid($vault_guid, $user_id);
 		return $vault;
 	}
 
+	/**
+	 * Create a new vault.
+	 * @param $vault_name
+	 * @param $userId
+	 * @return \OCA\Passman\Db\Vault
+	 */
 	public function createVault($vault_name, $userId) {
 		return $this->vaultMapper->create($vault_name, $userId);
 	}
 
+	/**
+	 * Update vault
+	 * @param $vault
+	 */
 	public function updateVault($vault) {
 		return $this->vaultMapper->updateVault($vault);
 	}
 
+	/**
+	 * Update last access time of a vault.
+	 * @param $vault_id
+	 * @param $user_id
+	 */
 	public function setLastAccess($vault_id, $user_id){
 		return $this->vaultMapper->setLastAccess($vault_id, $user_id);
 	}
 
+	/**
+	 * Uodate sharing keys of a vault.
+	 * @param $vault_id
+	 * @param $privateKey
+	 * @param $publicKey
+	 */
 	public function updateSharingKeys($vault_id, $privateKey, $publicKey){
 		return $this->vaultMapper->updateSharingKeys($vault_id, $privateKey, $publicKey);
 	}