Improve documentation.

Author: gkellogg

.yardopts

@@ -0,0 +1,14 @@
+--title "W3C Linked Data Patch Format for RDF.rb."
+--output-dir doc/yard
+--protected
+--no-private
+--hide-void-return
+--markup markdown
+--readme README.md
+-
+AUTHORS
+VERSION
+LICENSE
+etc/ld-patch.html
+etc/earl.ttl
+etc/earl.html

AUTHORS

@@ -0,0 +1 @@
+* Gregg Kellogg <gregg@greggkellogg.net>

README.md

@@ -3,24 +3,79 @@
 This is a [Ruby][] implementation of [LD Patch][] for [RDF.rb][].
 
 [![Gem Version](https://badge.fury.io/rb/ld-patch.png)](http://badge.fury.io/rb/ld-patch)
-
 [![Build Status](https://travis-ci.org/ruby-rdf/ld-patch.png?branch=master)](http://travis-ci.org/ruby-rdf/ld-patch)
-
 [![Coverage Status](https://coveralls.io/repos/ruby-rdf/ld-patch/badge.svg)](https://coveralls.io/r/ruby-rdf/ld-patch)
 
+## Description
+
+This gem implements the [LD Patch][] specification with a couple of changes and/or limitations:
+
+* The `INDEX` terminal was replaced by `INTEGER`. Having two terminals matching the same token strings causes a conflict. As a result, a _slice_ may contain positive integers, as well as unsigned and negative-integers.
+* The _graph_ rule is changed to the following:
+
+      [18]    graph           ::=     triples  ('.' triples?)*
+
+  This is necessary as the specified production is not context-free. As a result, it is possible for a graph to contain multiple trailing "`.`".
+
+[LD Patch][] is useful inside a Rack container where it can respond to `POST` messages to affect the modification of a _target graph_ identified using the URL of the `POST`.
+
 ## Features
 
 * 100% free and unencumbered [public domain](http://unlicense.org/) software.
 * Complete [Linked Data Patch Format][LD Patch] parsing and execution
 * Implementation Report: {file:etc/earl.html EARL}
 * Compatible with Ruby >= 2.0.0.
 
-## Description
+## Documentation
+Full documentation available on [Rubydoc.info][LD-Patch doc]
+
+## Implementation Notes
+The reader uses the [EBNF][] gem to generate first, follow and branch tables, and uses the `Parser` and `Lexer` modules to implement the LD Patch parser.
+
+The parser takes branch and follow tables generated from the [LD Patch Grammar](file.ld-patch.html) described in the [specification][LD Patch]. Branch and Follow tables are specified in the generated {LD::Patch::Meta}.
+
+## Dependencies
+
+* [Ruby](http://ruby-lang.org/) (>= 2.0.0)
+* [RDF.rb](http://rubygems.org/gems/rdf) (>= 1.1.15)
+* [EBNF][] (>= 0.3.0)
+* [SPARQL][] (>= 1.1.7)
+* [SXP][] (>= 0.1.5)
+* [RDF::XSD][] (>= 1.1.4)
+
+## Mailing List
+* <http://lists.w3.org/Archives/Public/public-rdf-ruby/>
+
+## Author
+* [Gregg Kellogg](http://github.com/gkellogg) - <http://greggkellogg.net/>
+
+## Contributing
+This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange development and release activity. All submissions _must_ be on a feature branch based on the _develop_ branch to ease staging and integration.
+
+* Do your best to adhere to the existing coding conventions and idioms.
+* Don't use hard tabs, and don't leave trailing whitespace on any line.
+* Do document every method you add using [YARD][] annotations. Read the [tutorial][YARD-GS] or just look at the existing code for examples.
+* Don't touch the `.gemspec`, `VERSION` or `AUTHORS` files. If you need to change them, do so on your private branch only.
+* Do feel free to add yourself to the `CREDITS` file and the corresponding list in the the `README`. Alphabetical order applies.
+* Do note that in order for us to merge any non-trivial changes (as a rule of thumb, additions larger than about 15 lines of code), we need an explicit [public domain dedication][PDD] on record from you.
+
+## License
+This is free and unencumbered public domain software. For more information,
+see <http://unlicense.org/> or the accompanying {file:LICENSE} file.
+
+A copy of the [LD Patch EBNF](file:etc/ld-patch.ebnf) and derived parser files are included in the repository, which are not covered under the UNLICENSE. These files are covered via the [W3C Document License](http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231).
 
-[Ruby]:             http://ruby-lang.org/
-[RDF]:              http://www.w3.org/RDF/
-[RDF.rb]:           http://rdf.rubyforge.org/
-[Linked Data]:      http://rubygems.org/gems/linkeddata
-[LD Patch]:         http://www.w3.org/TR/ldpatch/
-[SSE]:              http://openjena.org/wiki/SSE
-[SXP]:              http://sxp.rubyforge.org/
+[Ruby]:           http://ruby-lang.org/
+[RDF]:            http://www.w3.org/RDF/
+[YARD]:           http://yardoc.org/
+[YARD-GS]:        http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
+[PDD]:             http://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html
+[RDF.rb]:         http://rubygems.org/gems/rdf
+[RDF::XSD]:       http://rubygems.org/gems/rdf-xsd
+[EBNF]:           http://rubygems.org/gems/ebnf
+[SPARQL]:         http://rubygems.org/gems/sparql
+[Linked Data]:    http://rubygems.org/gems/linkeddata
+[SSE]:            http://openjena.org/wiki/SSE
+[SXP]:            http://rubygems.org/gems/sxp-ruby
+[LD Patch]:       http://www.w3.org/TR/ldpatch/
+[LD-Patch doc]:   http://rubydoc.info/github/ruby-rdf/ld-patch

lib/ld/patch/algebra/bind.rb

@@ -61,7 +61,7 @@ class Bind < SPARQL::Algebra::Operator::Ternary
     #   the graph or repository to write
     # @param  [Hash{Symbol => Object}] options
     #   any additional options
-    # @param [RDF::Query::Solutions] bindings
+    # @option options [RDF::Query::Solutions] :bindings
     # @return [RDF::Query::Solutions] A single solution including passed bindings with `var` bound to the solution.
     # @raise [Error]
     #   If path does not evaluate to a single term

lib/ld/patch/parser.rb

@@ -364,6 +364,7 @@ def to_s
       @result.to_sxp
     end
 
+    alias_method :ll1_parse, :parse
     # Parse patch
     #
     # The result is an S-List. Productions return an array such as the following:
@@ -373,8 +374,6 @@ def to_s
     # @param [Symbol, #to_s] prod The starting production for the parser.
     #   It may be a URI from the grammar, or a symbol representing the local_name portion of the grammar URI.
     # @return [Array]
-    alias_method :ll1_parse, :parse
-
     def parse(prod = START)
       ll1_parse(@input, prod.to_sym, @options.merge(branch: BRANCH,
                                                     first: FIRST,