General repo refresh.

.travis.env

@@ -1 +1 @@
-W0fBKMjZM4l7SzwhvUxq7Of9QaQqjeV90H8U5zpMis5fb11m2dkPpqqQ3b66jJxeEnHuOaLL31J78jIDhta322sE0ljpTtxhMiIlCVc+HpY/KbAlsx/02294luV5Q1Fn8LRtJJ2hhiaHtFngjCii56U/WCH6V+Pp4qzhFjuhPj4=
+Lq96YFvZO96AafxxILw4JHDpDLHcvfyfPl8AIIW7SIqiI4uMnCkgUlsnZy5E8xHeTC3em5580Y8vPtWCqJqOON3Q3KtthI9aCHr/fryCq5UvbCxssP7AOw/4K+R2OesDNy0CvQMW4PtO8qyC7SI9DRYyxPwBQSi+mSu2ClCLFhY=

.travis.install

@@ -4,23 +4,32 @@
  * This script is executed before composer dependencies are installed,
  * and as such must be included in each project as part of the skeleton.
  */
-if ($token = getenv('ARCHER_TOKEN')) {
-    $config = array(
-        'config' => array(
-            'github-oauth' => array('github.com' => $token)
-        )
-    );
 
-    $file = '~/.composer/config.json';
-    $dir  = dirname($file);
-    if (!is_dir($dir)) {
-        mkdir($dir, 0755, true);
-    }
-    file_put_contents($file, json_encode($config));
+$config = array(
+    'config' => array(
+        'notify-on-install' => false
+    )
+);
 
+if ($token = getenv('ARCHER_TOKEN')) {
+    $config['config']['github-oauth'] = array(
+        'github.com' => $token
+    );
     $composerFlags = '--prefer-dist';
+    passthru('curl -s -i -H "Authorization: token $ARCHER_TOKEN" https://api.github.com | grep "^X-RateLimit"');
 } else {
     $composerFlags = '--prefer-source';
 }
 
-passthru('composer install --dev --no-progress --no-interaction --ansi ' . $composerFlags);
+$file = '~/.composer/config.json';
+$dir  = dirname($file);
+if (!is_dir($dir)) {
+    mkdir($dir, 0755, true);
+}
+file_put_contents($file, json_encode($config));
+
+passthru('composer self-update --no-interaction');
+
+$exitCode = 0;
+passthru('composer install --dev --no-progress --no-interaction --ansi ' . $composerFlags, $exitCode);
+exit($exitCode);

.travis.yml

@@ -8,22 +8,14 @@
 #
 language: php
 
-php:
-  - 5.3
-  - 5.4
-  - 5.5
+php: ["5.3", "5.4", "5.5"]
 
 env:
   global:
     - ARCHER_PUBLISH_VERSION=5.4
-    - secure: "W0fBKMjZM4l7SzwhvUxq7Of9QaQqjeV90H8U5zpMis5fb11m2dkPpqqQ3b66jJxeEnHuOaLL31J78jIDhta322sE0ljpTtxhMiIlCVc+HpY/KbAlsx/02294luV5Q1Fn8LRtJJ2hhiaHtFngjCii56U/WCH6V+Pp4qzhFjuhPj4="
+    - secure: "Lq96YFvZO96AafxxILw4JHDpDLHcvfyfPl8AIIW7SIqiI4uMnCkgUlsnZy5E8xHeTC3em5580Y8vPtWCqJqOON3Q3KtthI9aCHr/fryCq5UvbCxssP7AOw/4K+R2OesDNy0CvQMW4PtO8qyC7SI9DRYyxPwBQSi+mSu2ClCLFhY="
 
 install:
   - ./.travis.install
 script:
   - ./vendor/bin/archer travis:build
-
-matrix:
-  # PHP 5.5 is still in alpha, so ignore build failures.
-  allow_failures:
-    - php: 5.5

CHANGELOG.md

@@ -1,7 +1,20 @@
 # Blox changelog
 
-### 2.0.0
+### 3.0.0 (unreleased)
 
-* [Archer](https://github.com/IcecaveStudios/archer) integration
-* Removed Visita integration
-* Implemented changelog
+- **[BC BREAK]** `AST` namespace renamed to `Element`
+- **[BC BREAK]** Interfaces renamed to match naming conventions
+- **[BC BREAK]** `DocumentationBlock` method `tagsbyName` renamed to
+  `tagsByName`
+- **[NEW]** Added documentation
+- **[IMPROVED]** Summary text now collapses whitespace
+- **[IMPROVED]** Tag content can now span multiple lines
+- **[MAINTENANCE]** General repository maintenance
+
+### 2.0.0 (2013-03-04)
+
+- **[NEW]** [Archer] integration
+- **[IMPROVED]** Removed Visita integration
+- **[NEW]** Implemented changelog
+
+[Archer]: https://github.com/IcecaveStudios/archer

README.md

@@ -5,11 +5,126 @@
 [![Build Status]](http://travis-ci.org/eloquent/blox)
 [![Test Coverage]](http://eloquent-software.com/blox/artifacts/tests/coverage/)
 
-## Installation
+## Installation and documentation
 
-Available as [Composer](http://getcomposer.org/) package
-[eloquent/blox](https://packagist.org/packages/eloquent/blox).
+* Available as [Composer] package [eloquent/blox].
+* [API documentation] available.
 
-<!-- references -->
-[Build Status]: https://raw.github.com/eloquent/blox/gh-pages/artifacts/images/icecave/regular/build-status.png
-[Test Coverage]: https://raw.github.com/eloquent/blox/gh-pages/artifacts/images/icecave/regular/coverage.png
+## What is *Blox*?
+
+*Blox* is a parser for PHP block comment documentation. *Blox* allows a standard
+documentation block comment to be parsed into an object tree representation,
+with a simple interface for retrieving information.
+
+## Usage
+
+```php
+use Eloquent\Blox\BloxParser;
+
+$blockComment = <<<'EOD'
+/**
+ * This is the summary.
+ *     This is also the summary.
+ *
+ * This is the body.
+ *
+ * This is also the body.
+ *
+ * @tagA This is some tag content.
+ * @tagA This is some more tag content.
+ * @tagB This is content for a different tag
+ *     which spans multiple lines.
+ *
+ * This is ignored.
+ */
+EOD;
+
+$parser = new BloxParser;
+$block = $parser->parseBlockComment($blockComment);
+
+echo $block->summary(); // outputs 'This is the summary. This is also the summary.'
+echo $block->body();    // outputs "This is the body.\n\nThis is also the body."
+
+// outputs 'This is some tag content.', then 'This is some more tag content.'
+foreach ($block->tagsByName('tagA') as $tag) {
+    echo $tag->content();
+}
+
+$splatTags = $block->tagsByName('tagB');
+echo array_pop($splatTags)->content(); // outputs 'This is content for a different tag which spans multiple lines.'
+```
+
+## Conventions
+
+*Blox* has a small set of conventions for block comments. They aim to be quite
+loose, so that *Blox* can be used, regardless of the body text format in use.
+
+### Summary text
+
+The summary text starts from the first non-blank line and continues until a
+blank line, or the end of the block is encountered. White space at the beginning
+of lines, and newlines, are collapsed into a single space.
+
+```php
+/**
+ * This is the summary.
+ *     This is also the summary.
+ *
+ * This is not the summary.
+ */
+```
+
+### Body text
+
+The body text starts from the first non-blank line after the summary, and
+continues until a tag, or the end of the block is encountered. White space and
+newlines are left as-is.
+
+```php
+/**
+ * This is not the body.
+ *
+ * This is the body.
+ *
+ * This is also the body.
+ *
+ * @tagA This is not the body.
+ */
+```
+
+### Tags
+
+A tag is any line starting with the 'at' symbol (`@`) followed by one or more
+'word' characters (as defined in [PCRE]). These 'word' characters make up the
+tag's 'name'.
+
+Tags can optionally be followed by content which will be associated with the
+tag. White space directly after the tag name is ignored, but subsequent text is
+included in the tag content, as are subsequent lines until a blank line or
+another tag is encountered. White space at the beginning of lines, and newlines,
+are collapsed into a single space.
+
+```php
+/**
+ * This is not a tag.
+ *
+ * @tagA This is some tag content.
+ * @tagA This is some more tag content.
+ * @tagB This is content for a different tag
+ *     which spans multiple lines.
+ *
+ * This is ignored.
+ */
+```
+
+<!-- References -->
+
+[API documentation]: http://lqnt.co/blox/artifacts/documentation/api/
+[Composer]: http://getcomposer.org/
+[eloquent/blox]: https://packagist.org/packages/eloquent/blox
+[PCRE]: http://php.net/pcre
+
+[Build Status]: https://api.travis-ci.org/eloquent/blox.png?branch=master
+[Latest build]: https://travis-ci.org/eloquent/blox
+[Test coverage report]: https://coveralls.io/r/eloquent/blox
+[Test Coverage]: https://coveralls.io/repos/eloquent/blox/badge.png?branch=master

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "eloquent/blox",
     "description": "A parser for block comment documentation.",
-    "keywords": ["documentation","parser","comment","block","docblock","phpdoc","phpdocumentor","annotation","tag"],
+    "keywords": ["documentation", "parser", "comment", "block", "docblock", "phpdoc", "phpdocumentor", "annotation", "tag"],
     "homepage": "https://github.com/eloquent/blox",
     "license": "MIT",
     "authors": [
@@ -12,10 +12,10 @@
         }
     ],
     "require": {
-        "php": ">=5.3.0"
+        "php": ">=5.3"
     },
     "require-dev": {
-        "icecave/archer": "~0.2"
+        "icecave/archer": "1.0.0-alpha.2"
     },
     "autoload": {
         "psr-0": {