search

riak-ripple / ripple

A rich Ruby modeling layer for Riak, Basho's distributed database
Other
619 stars 152 forks source link

Add documentation for the conflict resolution API. #237

Closed myronmarston closed 12 years ago

myronmarston commented 12 years ago

Seeing @seancribbs' slides from his recent talk on eventual consistency and conflict resolution with riak/ripple reminded me that I never properly documented the conflict resolution API.

I've never used YARD before so hopefully this looks OK.

seancribbs commented 12 years ago

@myronmarston Looks great! Just run the :yard task to see if the output is sane. YARD and github markup don't agree so I'll have to correct some of those places where I use the triple-backtick soon.

myronmarston commented 12 years ago

Just run the :yard task to see if the output is sane.

I spent a while this morning trying rake -T at the root level and in ripple and riak-client to see if there was a yard task and I couldn't find one. Now I see that the rakefile attempts to load yard and silently fails if it can't find. Even after installing yard, I get errors:

➜  ripple git:(conflict_resolution_documentation) rake yard --trace
(in /Users/myron/code/ripple)
** Invoke yard (first_time)
** Execute yard
[warn]: Syntax error in `license`:(1,24): syntax error, unexpected tconstant, expecting $end
[error]: ParserSyntaxError: syntax error in `LICENSE`:(1,24): syntax error, unexpected tCONSTANT, expecting $end
[error]: Stack trace:
    /Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:505:in `on_parse_error'
    /Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:49:in `parse'
    /Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:49:in `parse'
    /Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:15:in `parse'
    /Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/parser/source_parser.rb:438:in `parse'
    /Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/parser/source_parser.rb:361:in `parse_in_order'

[warn]: Unknown tag @options in file `riak-client/lib/riak/client/http_backend.rb` near line 103
[warn]: Unknown tag @options in file `riak-client/lib/riak/client/http_backend.rb` near line 103
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':150: Cannot resolve link to :query from text:
[warn]: ...{:query => "archived"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#58;&#115;&#x65;&#97;&#x6e;&#x40;&#98;&#x61;&#115;&#104;&#111;&#46;&#x63;&#x6f;&#x6d;">&#x73;&#x65;&#x61;&#110;&#64;&#98;&#97;&#115;&#104;&#111;&#46;&#x63;&#111;&#109;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':150: Cannot resolve link to :query from text:
[warn]: ...{:query => "archived"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[warn]: In file `README.markdown':141: Cannot resolve link to :id from text:
[warn]: ...{:id => "<a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#115;&#x65;&#97;&#110;&#x40;&#x62;&#x61;&#115;&#x68;&#111;&#46;&#99;&#111;&#109;">&#115;&#101;&#97;&#x6e;&#64;&#x62;&#x61;&#115;&#x68;&#111;&#x2e;&#99;&#x6f;&#x6d;</a>", :name => "Sean Cribbs"}...
[error]: Missing 'redcloth' gem for Textile formatting. Install it with `gem install redcloth`
rake aborted!
undefined method `new' for nil:NilClass
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/helpers/html_helper.rb:79:in `html_markup_textile'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/helpers/html_helper.rb:41:in `htmlify'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/layout/html/setup.rb:49:in `diskfile'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:314:in `render_section'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:210:in `block (2 levels) in run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:207:in `each'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:207:in `block in run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:345:in `add_options'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:206:in `run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:228:in `block in yieldall'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:359:in `with_section'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:228:in `yieldall'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/layout/html/layout.erb:22:in `_erb_cache_5'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:238:in `erb'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:316:in `render_section'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:210:in `block (2 levels) in run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:207:in `each'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:207:in `block in run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:345:in `add_options'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:206:in `run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:91:in `run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/fulldoc/html/setup.rb:72:in `block in serialize_file'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/engine.rb:115:in `with_serializer'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/fulldoc/html/setup.rb:71:in `serialize_file'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/fulldoc/html/setup.rb:10:in `block in init'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/fulldoc/html/setup.rb:9:in `each'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/fulldoc/html/setup.rb:9:in `each_with_index'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/templates/default/fulldoc/html/setup.rb:9:in `init'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:144:in `initialize'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:86:in `new'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/template.rb:91:in `run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/templates/engine.rb:103:in `generate'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/cli/yardoc.rb:306:in `run_generate'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/cli/yardoc.rb:219:in `run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/yard-0.7.3/lib/yard/rake/yardoc_task.rb:65:in `block in define'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:636:in `call'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:636:in `block in execute'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:631:in `each'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:631:in `execute'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:597:in `block in invoke_with_call_chain'
/Users/myron/.rvm/rubies/ruby-1.9.2-p290/lib/ruby/1.9.1/monitor.rb:201:in `mon_synchronize'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:590:in `invoke_with_call_chain'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:583:in `invoke'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2051:in `invoke_task'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2029:in `block (2 levels) in top_level'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2029:in `each'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2029:in `block in top_level'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2068:in `standard_exception_handling'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2023:in `top_level'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2001:in `block in run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:2068:in `standard_exception_handling'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/lib/rake.rb:1998:in `run'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/gems/rake-0.8.7/bin/rake:31:in `<top (required)>'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/bin/rake:19:in `load'
/Users/myron/.rvm/gems/ruby-1.9.2-p290@ripple/bin/rake:19:in `<main>'

I manually installed yard and used yard server --reload to browse the docs and they looked OK.

myronmarston commented 12 years ago

I just rebased and merged this.