https://github.com/bugadani/annotiny
Miny-Annotation is an Annotation reader for the Miny Framework.
https://github.com/bugadani/annotiny
Last synced: 8 months ago
JSON representation
Miny-Annotation is an Annotation reader for the Miny Framework.
- Host: GitHub
- URL: https://github.com/bugadani/annotiny
- Owner: bugadani
- License: mit
- Created: 2014-01-21T17:50:03.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2016-05-05T08:30:47.000Z (about 10 years ago)
- Last Synced: 2025-03-02T15:28:31.414Z (over 1 year ago)
- Language: PHP
- Size: 78.1 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/bugadani/Annotiny)
Annotiny
========
Annotiny is a small library designed to read and parse documentation comments.
Usage
--------
To create the AnnotationReader object a suitable parser must be supplied.
```
$parser = new \Annotiny\AnnotationParser(new \Annotiny\AnnotationContainer);
$annotationReader = new \Annotiny\AnnotationReader($parser, $factory);
```
Annotation has four public methods: `readClass($class)`, `readFunction($function)`, `readMethod($class, $method)` and `readProperty($class, $property)`. These functions work as one would expect, e.g. `readMethod` reads and parses the documentation comment of a class or object method.
### The Comment object
The resulting data structure of a `read*` method is a Comment instance. Comments hold the description and the parsed tags of the documentation comment.
Comment provides several useful methods to work with the annotation tags.
* `has($tag)` checks if a tag is present
* `get($tag)` retrieves the tag value
* `equals($tag, $value)` checks if the value of `$tag` equals to `$value`
* `contains($tag, $value)` checks if `$value` is present in the argument list of the annotation
* `containsAll($tag, $value_array)` checks if each member of `$value_array` is present
* `getDescription()` returns the description part of the comment
If a tag is not found, an `OutOfBoundsException` is thrown.
Comment syntax
--------
A documentation comment is directly (e.g. no blank lines between them) above the documented class, function, method or property. The comment begins with `/**` and end with `*/`. Every line should optionally begin with an asterisk (*).
The comment begins with the description part that is terminated by a `@tag`.
### Examples:
/** This is a one-liner */
/**
* Multiple lines
*
* @annotation
*/
Annotation syntax
--------
Annotation tags are preceded with an at-sign (@) and they start on a new line. The tag name can consist of letters, numbers, dash (-) and underscode (_) signs but must begin with at least one letter. The following are examples of invalid tag names: `@1tag`, `@-tag`.
There are three types of annotations:
* Simple annotations that do not have values (`@tag`)
* Annotations that are followed by their values (`@tag that has a value`).
* Annotations that are followed by parameter list (`@tag(value, 'other value')`.
The values are strings delimited by commas. In the secound case only one value is allowed, commas and the following text are discarded. The third case allowes multiple values that are separated by commas. To allow commas and newlines in the value, simply enclose it in ' or ".
If multiple annotations are present with the same name, their values will be aggregated in an array. In this case, annotations without values will be ignored.
Note: named parameters are supported in the parameter list syntax. In this case an `=` sign separates the name and the value.
### Examples:
* `@tag`
* `@tag value`
* `@tag "some value"`
* `@tag()`
* `@tag(simple value)`
* `@tag(multiple, values)`
* `@tag(name='value')`