Update documentation;

README.md

@@ -11,12 +11,15 @@ local docroc = require 'docroc'
 local comments = docroc.process('file.lua')
 ```
 
-`comments` is now a table of comment blocks in the file, each with a table of `tags` and a `context` key. The `tags` table is an array of the tags, but also groups the tags by type. The `context` key is a string containing the contents of the line after the comment block.
+`comments` is now a table of comment blocks in the file, each with a table of `tags` and a `context`
+key. The `tags` table is an array of the tags, but also groups the tags by type. The `context` key
+is a string containing the contents of the line after the comment block.
 
 Notes on parsing:
 
 - A comment block must start with three dashes. It ends on the next non-commented line.
-- Tags are recognized as any sequence of letters that start with `@`, and continue until the next tag is encountered. The first tag is implicitly `@description`.
+- Tags are recognized as any sequence of letters that start with `@`, and continue until the next
+tag is encountered. The first tag is implicitly `@description`.
 
 Example
 ---
@@ -42,12 +45,11 @@ to this:
     tags = {
       [1] = {
         tag = 'description',
-        raw = 'The person to greet.',
         text = 'The person to greet.'
       },
       [2] = {
         tag = 'arg',
-        raw = '{string=} name - The person to greet',
+        text = '{string=} name - The person to greet',
         type = 'string',
         optional = true,
         name = 'name',
@@ -55,7 +57,7 @@ to this:
       },
       [3] = {
         tag = 'returns',
-        raw = '{number}',
+        text = '{number}',
         type = 'number'
       },
       description = {...},
@@ -66,6 +68,48 @@ to this:
 }
 ```
 
+Processors
+---
+
+By default, when docroc finds a tag, it creates an entry with two keys: `tag` and `text`.  `tag`
+contains the name of the tag and `text` contains the text after the tag.  This behavior can be
+extended using the `docroc.processors` table:
+
+```lua
+docroc.processors.customTag = function(body)
+  return {
+    numberOfCharacters = #body,
+    reversed = body:reverse()
+  }
+end
+```
+
+Now, if we process a file containing the following:
+
+```lua
+--- @customTag hello world
+```
+
+We would get the following:
+
+```lua
+{
+  tag = 'customTag',
+  text = 'hello world',
+  numberOfCharacters = 11,
+  reversed = 'dlrow olleh'
+}
+```
+
+For convenience, docroc provides a default set of custom processors:
+
+- **arg**: Collects information on an argument to a function, including the `type` of the argument,
+whether or not it is `optional`, whether or not it has a `default` value, its `name`, and a
+`description`.  The expected structure is `@arg {<type>=<default>} <name> - <description>`, all of
+which are optional.  An equals sign after the type represents an optional argument.
+- **returns**: Similar to `@arg`, contains information on a return value of the function.  It
+returns `type` and `description` keys, and expects a structure of `@returns {<type>} <description>`.
+
 Related
 ---