From c2b4e534534e083147bbad9b564179832cfa2912 Mon Sep 17 00:00:00 2001
From: Bart Visscher <bartv@thisnet.nl>
Date: Fri, 5 Oct 2012 17:42:42 +0200
Subject: [PATCH] Add API description to OC_Route and OC_Router

---
 lib/route.php  | 40 ++++++++++++++++++++++++++++++++++++++++
 lib/router.php | 31 +++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/lib/route.php b/lib/route.php
index c5a8bd2aa3..89af829d3d 100644
--- a/lib/route.php
+++ b/lib/route.php
@@ -9,31 +9,53 @@
 use Symfony\Component\Routing\Route;
 
 class OC_Route extends Route {
+	/**
+	 * Specify the method when this route is to be used
+	 *
+	 * @param string $method HTTP method (uppercase)
+	 */
 	public function method($method) {
 		$this->setRequirement('_method', strtoupper($method));
 		return $this;
 	}
 
+	/**
+	 * Specify POST as the method to use with this route
+	 */
 	public function post() {
 		$this->method('POST');
 		return $this;
 	}
 
+	/**
+	 * Specify GET as the method to use with this route
+	 */
 	public function get() {
 		$this->method('GET');
 		return $this;
 	}
 
+	/**
+	 * Specify PUT as the method to use with this route
+	 */
 	public function put() {
 		$this->method('PUT');
 		return $this;
 	}
 
+	/**
+	 * Specify DELETE as the method to use with this route
+	 */
 	public function delete() {
 		$this->method('DELETE');
 		return $this;
 	}
 
+	/**
+	 * Defaults to use for this route
+	 *
+	 * @param array $defaults The defaults
+	 */
 	public function defaults($defaults) {
 		$action = $this->getDefault('action');
 		$this->setDefaults($defaults);
@@ -44,6 +66,11 @@ class OC_Route extends Route {
 		return $this;
 	}
 
+	/**
+	 * Requirements for this route
+	 *
+	 * @param array $requirements The requirements
+	 */
 	public function requirements($requirements) {
 		$method = $this->getRequirement('_method');
 		$this->setRequirements($requirements);
@@ -56,6 +83,14 @@ class OC_Route extends Route {
 		return $this;
 	}
 
+	/**
+	 * The action to execute when this route matches
+	 * @param string|callable $class the class or a callable
+	 * @param string $function the function to use with the class
+	 *
+	 * This function is called with $class set to a callable or
+	 * to the class with $function
+	 */
 	public function action($class, $function = null) {
 		$action = array($class, $function);
 		if (is_null($function)) {
@@ -65,6 +100,11 @@ class OC_Route extends Route {
 		return $this;
 	}
 
+	/**
+	 * The action to execute when this route matches, includes a file like
+	 * it is called directly
+	 * @param $file
+	 */
 	public function actionInclude($file) {
 		$function = create_function('$param', 'unset($param["_route"]);$_GET=array_merge($_GET,$param);unset($param);require_once "'.$file.'";');
 		$this->action($function);
diff --git a/lib/router.php b/lib/router.php
index 04a3d41006..a471a06802 100644
--- a/lib/router.php
+++ b/lib/router.php
@@ -53,16 +53,34 @@ class OC_Router {
 		return $this->collections[$name];
 	}
 
+	/**
+	 * Sets the collection to use for adding routes
+	 *
+	 * @param string $name Name of the colletion to use.
+	 */
 	public function useCollection($name) {
 		$this->collection = $this->getCollection($name);
 	}
 
+	/**
+	 * Create a OC_Route.
+	 *
+	 * @param string $name Name of the route to create.
+	 * @param string $pattern The pattern to match
+	 * @param array  $defaults     An array of default parameter values
+	 * @param array  $requirements An array of requirements for parameters (regexes)
+	 */
 	public function create($name, $pattern, array $defaults = array(), array $requirements = array()) {
 		$route = new OC_Route($pattern, $defaults, $requirements);
 		$this->collection->add($name, $route);
 		return $route;
 	}
 
+	/**
+	 * Find the route matching $url.
+	 *
+	 * @param string $url The url to find
+	 */
     	public function match($url) {
 		$matcher = new UrlMatcher($this->root, $this->context);
 		$parameters = $matcher->match($url);
@@ -81,6 +99,10 @@ class OC_Router {
 		}
 	}
 
+	/**
+	 * Get the url generator
+	 *
+	 */
 	public function getGenerator()
 	{
 		if (null !== $this->generator) {
@@ -90,11 +112,20 @@ class OC_Router {
 		return $this->generator = new UrlGenerator($this->root, $this->context);
 	}
 
+	/**
+	 * Generate url based on $name and $parameters
+	 *
+	 * @param string $name Name of the route to use.
+	 * @param array $parameters Parameters for the route
+	 */
 	public function generate($name, $parameters = array(), $absolute = false)
 	{
 		return $this->getGenerator()->generate($name, $parameters, $absolute);
 	}
 
+	/**
+	 * Generate JSON response for routing in javascript
+	 */
 	public static function JSRoutes()
 	{
 		// TODO: http caching