Skip to content

Commit

Permalink
Improved documentation by
Browse files Browse the repository at this point in the history 
- removing tables in comments documentation
- rendering the html version of the documentation with proper hyperlinks
  • Loading branch information
@Arul-
Arul- committed Aug 11, 2013
1 parent 0ef0205 commit 1c3432e
Show file tree
Hide file tree
Showing 6 changed files with 761 additions and 478 deletions.
314 changes: 162 additions & 152 deletions ANNOTATIONS.md
View file
Original file line number Diff line number Diff line change
@@ -1,156 +1,166 @@
Supported Annotations
---------------------
# Supported Annotations

You may use the following php doc comments to annotate your methods.
All tags except @url can also be defined at the class level.

<table>
<tr>
<th>Tag</th>
<th>Description</th>
</tr>
<tr>
<td>@url</td>
<td>
Syntax:
<pre>@url GET|POST|PUT|PATCH|DELETE custom/{dynamic}/route</pre>
Example:
<pre>@url POST authors/{id}/books</pre>
Overrides auto routes and creates manual routes. use as many as you need
</td>
</tr>
<tr>
<td>@access</td>
<td>
Syntax:
<pre>@access private|public|protected|hybrid</pre>
Example:
<pre>@access protected</pre>
Access control for api methods. PHPDoc only supports private and public,
Restler adds <b>protected</b> for api that needs authentication,
<b>hybrid</b> for api that enhances resulting data for authenticated users.
</td>
</tr>
<tr>
<td>@smart-auto-routing</td>
<td>
Syntax:
<pre>@smart-auto-routing true|false</pre>
Example:
<pre>@smart-auto-routing false</pre>
Smart auto routing is enabled by default. Avoids creating multiple
routes that can increase the ambiguity when set to true. when a method
parameter is optional it is not mapped to the url and should only be
used in request body or as query string `/resource?id=value`.
When a parameter is required and is scalar, it will be mapped as
part of the url `/resource/{id}`
</td>
</tr>
<tr>
<td>@class</td>
<td>
Syntax:
<pre>@class ClassName {@propertyName value}</pre>
Example:
<pre>@class AccessControl {@requires user} {@level 5}</pre>
Inject property of the specified class with specified value
</td>
</tr>
<tr>
<td>@cache</td>
<td>
Syntax:
<pre>@cache headerCacheControlValue</pre>
Example:
<pre>@cache max-age={expires}, must-revalidate</pre>
Specify value to set CacheControl Header, it can use @expires value as
shown in the example
</td>
</tr>
<tr>
<td>@expires</td>
<td>
Syntax:
<pre>@expires numberOfSeconds</pre>
Example:
<pre>@expires 30</pre>
Sets the content to expire immediately when set to zero alternatively
you can specify the number of seconds the content will expire
</td>
</tr>
<tr>
<td>@throttle</td>
<td>
Syntax:
<pre>@throttle numberOfMilliSeconds</pre>
Example:
<pre>@throttle 3000</pre>
Sets the time in milliseconds for bandwidth throttling, which will
become the minimum response time for each API request.
</td>
</tr>
<tr>
<td>@status</td>
<td>
Syntax:
<pre>@status httpStatusCode</pre>
Example:
<pre>@status 201</pre>
Sets the HTTP Status code for the successful response.
</td>
</tr>
<tr>
<td>@header</td>
<td>
Syntax:
<pre>@header httpHeader</pre>
Example:
<pre>@header Link: &lt;meta.rdf>; rel=meta</pre>
Sets or overrides the specific HTTP Header.
</td>
</tr>
<tr>
<td>@param</td>
<td>
Syntax:
<pre>@param [type] Name [Description] {@name value}</pre>
Example:
<pre>@param int $num1 increment value {@min 5} {@max 100}</pre>
Standard @param comment that sets the type and description of a parameter.
Supported child attributes are documented under
<a href="PARAM.md">@param</a>
</td>
</tr>
<tr>
<td>@throws</td>
<td>
Syntax:
<pre>@throws httpStatusCode [Reason]</pre>
Example:
<pre>@throws 404 No Author for specified id</pre>
Documents possible error responses for the API call.
</td>
</tr>
<tr>
<td>@return</td>
<td>
Syntax:
<pre>@return type [Description]</pre>
Example:
<pre>@return Author an instance of iValueObject</pre>
Documents the structure of success response, user defined classes must
extend iValueObject.
</td>
</tr>
<tr>
<td>@var</td>
<td>
Syntax:
<pre>@var [type] [Description] {@name value}</pre>
Example:
<pre>@var int policy age {@min 18} {@max 100}</pre>
Stadard @var comments that are used with properties of model classes.
Supported child attributes are documented under <a href="PARAM.md">@param</a>
</td>
</tr>
</table>
## @url

Syntax:

@url GET|POST|PUT|PATCH|DELETE custom/{dynamic}/route

Example:

@url POST authors/{id}/books

Overrides auto routes and creates manual routes. use as many as you need

## @access

Syntax:

@access private|public|protected|hybrid

Example:

@access protected

Access control for api methods. PHPDoc only supports private and public, Restler adds protected for api that needs authentication, hybrid for api that enhances resulting data for authenticated users.


## @smart-auto-routing

Syntax:

@smart-auto-routing true|false

Example:

@smart-auto-routing false

Smart auto routing is enabled by default. Avoids creating multiple routes that can increase the ambiguity when set to true. when a method parameter is optional it is not mapped to the url and should only be used in request body or as query string
`/resource?id=value`. When a parameter is required and is scalar, it will be mapped as part of the url `/resource/{id}`


## @class

Syntax:

@class ClassName {@propertyName value}

Example:

@class AccessControl {@requires user} {@level 5}

Sets property of the specified class with specified value when the class is instantiated by Restler

## @cache

Syntax:

@cache headerCacheControlValue

Example:

@cache max-age={expires}, must-revalidate

Specify value to set CacheControl Header, it can use @expires value as shown in the example

## @expires

Syntax:

@expires numberOfSeconds

Example:

@expires 30

Sets the content to expire immediately when set to zero alternatively you can specify the number of seconds the content will expire

## @throttle

Syntax:

@throttle numberOfMilliSeconds

Example:

@throttle 3000

Sets the time in milliseconds for bandwidth throttling, which will become the minimum response time for each API request.

## @status

Syntax:

@status httpStatusCode

Example:

@status 201

Sets the HTTP Status code for the successful response.

## @header

Syntax:

@header httpHeader

Example:

@header Link: <meta.rdf>; rel=meta

Sets or overrides the specific HTTP Header.

## @param

Syntax:

@param [type] Name [Description] {@name value}

Example:

@param int $num1 increment value {@min 5} {@max 100}

Standard @param comment that sets the type and description of a parameter. Supported child attributes are documented under [@param](PARAM.md)

## @throws

Syntax:

@throws httpStatusCode [Reason]

Example:

@throws 404 No Author for specified id

Documents possible error responses for the API call.

## @return

Syntax:

@return type [Description]

Example:

@return Author an instance of iValueObject

Documents the structure of success response, user defined classes must extend iValueObject.


## @var

Syntax:

@var [type] [Description] {@name value}

Example:

@var int policy age {@min 18} {@max 100}

Stadard @var comments that are used with properties of model classes. Supported child attributes are documented under [@param](PARAM.md)

---------------
Loading

0 comments on commit 1c3432e

Please sign in to comment.