Merge pull request #6034 from owncloud/fix-api-documentation

Fix api documentation

lib/private/defaults.php

@@ -1,15 +1,13 @@
 <?php
 
-/**
- * Default strings and values which differ between the enterprise and the
- * community edition. Use the get methods to always get the right strings.
- */
-
-
 if (file_exists(OC::$SERVERROOT . '/themes/' . OC_Util::getTheme() . '/defaults.php')) {
 	require_once 'themes/' . OC_Util::getTheme() . '/defaults.php';
 }
 
+/**
+ * Default strings and values which differ between the enterprise and the
+ * community edition. Use the get methods to always get the right strings.
+ */
 class OC_Defaults {
 
 	private $theme;
@@ -48,6 +46,10 @@ class OC_Defaults {
 		return false;
 	}
 
+	/**
+	 * Returns the base URL
+	 * @return string URL
+	 */
 	public function getBaseUrl() {
 		if ($this->themeExist('getBaseUrl')) {
 			return $this->theme->getBaseUrl();
@@ -56,6 +58,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns the URL where the sync clients are listed
+	 * @return string URL
+	 */
 	public function getSyncClientUrl() {
 		if ($this->themeExist('getSyncClientUrl')) {
 			return $this->theme->getSyncClientUrl();
@@ -64,6 +70,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns the documentation URL
+	 * @return string URL
+	 */
 	public function getDocBaseUrl() {
 		if ($this->themeExist('getDocBaseUrl')) {
 			return $this->theme->getDocBaseUrl();
@@ -72,6 +82,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns the title
+	 * @return string title
+	 */
 	public function getTitle() {
 		if ($this->themeExist('getTitle')) {
 			return $this->theme->getTitle();
@@ -80,6 +94,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns the short name of the software
+	 * @return string title
+	 */
 	public function getName() {
 		if ($this->themeExist('getName')) {
 			return $this->theme->getName();
@@ -88,6 +106,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns entity (e.g. company name) - used for footer, copyright
+	 * @return string entity name
+	 */
 	public function getEntity() {
 		if ($this->themeExist('getEntity')) {
 			return $this->theme->getEntity();
@@ -96,6 +118,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns slogan
+	 * @return string slogan
+	 */
 	public function getSlogan() {
 		if ($this->themeExist('getSlogan')) {
 			return $this->theme->getSlogan();
@@ -104,6 +130,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns logo claim
+	 * @return string logo claim
+	 */
 	public function getLogoClaim() {
 		if ($this->themeExist('getLogoClaim')) {
 			return $this->theme->getLogoClaim();
@@ -112,6 +142,10 @@ class OC_Defaults {
 		}
 	}
 
+	/**
+	 * Returns short version of the footer
+	 * @return string short footer
+	 */
 	public function getShortFooter() {
 		if ($this->themeExist('getShortFooter')) {
 			$footer = $this->theme->getShortFooter();
@@ -123,6 +157,10 @@ class OC_Defaults {
 		return $footer;
 	}
 
+	/**
+	 * Returns long version of the footer
+	 * @return string long footer
+	 */
 	public function getLongFooter() {
 		if ($this->themeExist('getLongFooter')) {
 			$footer = $this->theme->getLongFooter();

lib/public/activity/iconsumer.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Activity/IConsumer interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Activity;

lib/public/activity/imanager.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Activity/IManager interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Activity;
@@ -47,7 +52,6 @@ interface IManager {
 	 *
 	 * $callable has to return an instance of OCA\Activity\IConsumer
 	 *
-	 * @param string $key
 	 * @param \Closure $callable
 	 */
 	function registerConsumer(\Closure $callable);

lib/public/appframework/app.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework/App class
+ */
+
 namespace OCP\AppFramework;
 
 

lib/public/appframework/controller.php

@@ -20,6 +20,10 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework\Controller class
+ */
 
 namespace OCP\AppFramework;
 
@@ -34,16 +38,19 @@ use OCP\IRequest;
 abstract class Controller {
 
 	/**
+	 * app container for dependency injection
 	 * @var \OCP\AppFramework\IAppContainer
 	 */
 	protected $app;
 
 	/**
+	 * current request
 	 * @var \OCP\IRequest
 	 */
 	protected $request;
 
 	/**
+	 * constructor of the controller
 	 * @param IAppContainer $app interface to the app
 	 * @param IRequest $request an instance of the request
 	 */

lib/public/appframework/http.php

@@ -20,10 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework\HTTP class
+ */
 
 namespace OCP\AppFramework;
 
-
+/**
+ * Base class which contains constants for HTTP status codes
+ */
 class Http {
 
 	const STATUS_CONTINUE = 100;

lib/public/appframework/http/jsonresponse.php

@@ -20,6 +20,10 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework\HTTP\JSONResponse class
+ */
 
 namespace OCP\AppFramework\Http;
 
@@ -30,10 +34,15 @@ use OCP\AppFramework\Http;
  */
 class JSONResponse extends Response {
 
+	/**
+	 * response data
+	 * @var array|object
+	 */
 	protected $data;
 
 
 	/**
+	 * constructor of JSONResponse
 	 * @param array|object $data the object or array that should be transformed
 	 * @param int $statusCode the Http status code, defaults to 200
 	 */
@@ -55,7 +64,7 @@ class JSONResponse extends Response {
 
 	/**
 	 * Sets values in the data json array
-	 * @param array|object $params an array or object which will be transformed
+	 * @param array|object $data an array or object which will be transformed
 	 *                             to JSON
 	 */
 	public function setData($data){

lib/public/appframework/http/response.php

@@ -20,6 +20,10 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework\HTTP\Response class
+ */
 
 namespace OCP\AppFramework\Http;
 

lib/public/appframework/http/templateresponse.php

@@ -20,6 +20,10 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework\HTTP\TemplateResponse class
+ */
 
 namespace OCP\AppFramework\Http;
 
@@ -29,14 +33,34 @@ namespace OCP\AppFramework\Http;
  */
 class TemplateResponse extends Response {
 
+	/**
+	 * name of the template
+	 * @var string
+	 */
 	protected $templateName;
+
+	/**
+	 * parameters
+	 * @var array
+	 */
 	protected $params;
+
+	/**
+	 * rendering type (admin, user, blank)
+	 * @var string
+	 */
 	protected $renderAs;
+
+	/**
+	 * app name
+	 * @var string
+	 */
 	protected $appName;
 
 	/**
-	 * @param string $templateName the name of the template
+	 * constructor of TemplateResponse
 	 * @param string $appName the name of the app to load the template from
+	 * @param string $templateName the name of the template
 	 */
 	public function __construct($appName, $templateName) {
 		$this->templateName = $templateName;

lib/public/appframework/iapi.php

@@ -20,6 +20,10 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework/IApi interface
+ */
 
 namespace OCP\AppFramework;
 

lib/public/appframework/middleware.php

@@ -20,6 +20,10 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * AppFramework\Middleware class
+ */
 
 namespace OCP\AppFramework;
 

lib/public/authentication/iapachebackend.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Authentication/IApacheBackend interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Authentication;

lib/public/db.php

@@ -37,6 +37,8 @@ class DB {
 	/**
 	 * Prepare a SQL query
 	 * @param string $query Query string
+	 * @param int $limit Limit of the SQL statement
+	 * @param int $offset Offset of the SQL statement
 	 * @return \MDB2_Statement_Common prepared SQL query
 	 *
 	 * SQL query via MDB2 prepare(), needs to be execute()'d!

lib/public/defaults.php

@@ -30,19 +30,27 @@
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
-/*
+/**
  * public api to access default strings and urls for your templates
  */
 class Defaults {
 
+	/**
+	 * \OC_Defaults instance to retrieve the defaults
+	 * @return string
+	 */
 	private $defaults;
 
+	/**
+	 * creates a \OC_Defaults instance which is used in all methods to retrieve the
+	 * actual defaults
+	 */
 	function __construct() {
 		$this->defaults = new \OC_Defaults();
 	}
 
 	/**
-	 * @breif get base URL for the organisation behind your ownCloud instance
+	 * get base URL for the organisation behind your ownCloud instance
 	 * @return string
 	 */
 	public function getBaseUrl() {
@@ -50,7 +58,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif link to the desktop sync client
+	 * link to the desktop sync client
 	 * @return string
 	 */
 	public function getSyncClientUrl() {
@@ -58,7 +66,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif base URL to the documentation of your ownCloud instance
+	 * base URL to the documentation of your ownCloud instance
 	 * @return string
 	 */
 	public function getDocBaseUrl() {
@@ -66,7 +74,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif name of your ownCloud instance
+	 * name of your ownCloud instance
 	 * @return string
 	 */
 	public function getName() {
@@ -74,7 +82,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif Entity behind your onwCloud instance
+	 * Entity behind your onwCloud instance
 	 * @return string
 	 */
 	public function getEntity() {
@@ -82,7 +90,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif ownCloud slogan
+	 * ownCloud slogan
 	 * @return string
 	 */
 	public function getSlogan() {
@@ -90,7 +98,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif logo claim
+	 * logo claim
 	 * @return string
 	 */
 	public function getLogoClaim() {
@@ -98,7 +106,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif footer, short version
+	 * footer, short version
 	 * @return string
 	 */
 	public function getShortFooter() {
@@ -106,7 +114,7 @@ class Defaults {
 	}
 
 	/**
-	 * @breif footer, long version
+	 * footer, long version
 	 * @return string
 	 */
 	public function getLongFooter() {

lib/public/files/alreadyexistsexception.php

@@ -20,8 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/AlreadyExistsException class
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;
 
+/**
+ * Exception for already existing files/folders
+ */
 class AlreadyExistsException extends \Exception {}

lib/public/files/entitytoolargeexception.php

@@ -20,8 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/EntityTooLargeException class
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;
 
+/**
+ * Exception for too large entity
+ */
 class EntityTooLargeException extends \Exception {}

lib/public/files/file.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/File interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;

lib/public/files/folder.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/Folder interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;

lib/public/files/invalidcontentexception.php

@@ -20,8 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/InvalidContentException class
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;
 
+/**
+ * Exception for invalid content
+ */
 class InvalidContentException extends \Exception {}

lib/public/files/invalidpathexception.php

@@ -20,8 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/InvalidPathException class
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;
 
+/**
+ * Exception for invalid path
+ */
 class InvalidPathException extends \Exception {}

lib/public/files/node.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/Node interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;

lib/public/files/notenoughspaceexception.php

@@ -20,8 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/NotEnoughSpaceException class
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;
 
+/**
+ * Exception for not enough space
+ */
 class NotEnoughSpaceException extends \Exception {}

lib/public/files/notfoundexception.php

@@ -20,8 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/NotFoundException class
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;
 
+/**
+ * Exception for not found entity
+ */
 class NotFoundException extends \Exception {}

lib/public/files/notpermittedexception.php

@@ -20,8 +20,16 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/NotPermittedException class
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;
 
+/**
+ * Exception for not permitted action
+ */
 class NotPermittedException extends \Exception {}

lib/public/files/storage.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Files/Storage interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP\Files;

lib/public/iaddressbook.php

@@ -20,6 +20,11 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * IAddressBook interface
+ */
+
 // use OCP namespace for all classes that are considered public.
 // This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP {

lib/public/icontainer.php

@@ -64,7 +64,7 @@ interface IContainer {
 	 * In case the parameter is false the service will be recreated on every call.
 	 *
 	 * @param string $name
-	 * @param callable $closure
+	 * @param \Closure $closure
 	 * @param bool $shared
 	 * @return void
 	 */

lib/public/idbconnection.php

@@ -45,7 +45,7 @@ interface IDBConnection {
 
 	/**
 	 * Used to get the id of the just inserted element
-	 * @param string $tableName the name of the table where we inserted the item
+	 * @param string $table the name of the table where we inserted the item
 	 * @return int the id of the inserted element
 	 */
 	public function lastInsertId($table = null);

lib/public/share.php

@@ -256,7 +256,7 @@ class Share {
 	/**
 	 * Get the item of item type shared with the current user
 	 * @param string $itemType
-	 * @param string $ItemTarget
+	 * @param string $itemTarget
 	 * @param int $format (optional) Format type must be defined by the backend
 	 * @return Return depends on format
 	 */
@@ -268,8 +268,8 @@ class Share {
 
 	/**
 	 * Get the item of item type shared with a given user by source
-	 * @param string $ItemType
-	 * @param string $ItemSource
+	 * @param string $itemType
+	 * @param string $itemSource
 	 * @param string $user User user to whom the item was shared
 	 * @return array Return list of items with file_target, permissions and expiration
 	 */