multi_json 1.1.0 → 1.2.0

data/.travis.yml

@@ -1,7 +1,9 @@
+language: ruby
 rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
-  - jruby
-  - rbx
-  - ree
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode

data/Gemfile

@@ -1,6 +1,7 @@
 source 'https://rubygems.org'
 
 gem 'json',      '~> 1.4', :require => nil
-gem 'yajl-ruby', '~> 1.0', :require => nil
+gem 'oj',        '~> 1.0', :require => nil, :platforms => [:ruby, :mswin, :mingw]
+gem 'yajl-ruby', '~> 1.0', :require => nil, :platforms => [:ruby, :mswin, :mingw]
 
 gemspec

data/README.md

@@ -3,42 +3,37 @@
 [travis]: http://travis-ci.org/intridea/multi_json
 [gemnasium]: https://gemnasium.com/intridea/multi_json
 
-Lots of Ruby libraries utilize JSON parsing in some form, and everyone has
-their favorite JSON library. In order to best support multiple JSON parsers and
-libraries, `multi_json` is a general-purpose swappable JSON backend library.
-You use it like so:
+Lots of Ruby libraries parse JSON and everyone has their favorite JSON coder.
+Instead of choosing a single JSON coder and forcing users of your library to be
+stuck with it, you can use MultiJSON instead, which will simply choose the
+fastest available JSON coder. Here's how to use it:
 
     require 'multi_json'
 
-    MultiJson.engine = :yajl
-    MultiJson.decode('{ "abc":"def" }') # decoded using Yajl
-
-    MultiJson.decode('{ "abc":"def" }', :symbolize_keys => true) # for symbol keys: {:abc => "def"}
-
-    MultiJson.engine = :json_gem
-    MultiJson.engine = MultiJson::Engines::JsonGem # equivalent to previous line
-    MultiJson.encode({ :abc => 'def' }) # encoded using the JSON gem
-
-    MultiJson.encode({ :abc => 'def' }, :pretty => true) # encoded in a pretty form (ignored if engine is ok_json)
+    MultiJson.decode('{"abc":"def"}') #=> {"abc" => "def"}
+    MultiJson.decode('{"abc":"def"}', :symbolize_keys => true) #=> {:abc => "def"}
+    MultiJson.encode({:abc => 'def'}) # convert Ruby back to JSON
+    MultiJson.encode({:abc => 'def'}, :pretty => true) # encoded in a pretty form (if supported by the coder)
 
 The `engine` setter takes either a symbol or a class (to allow for custom JSON
 parsers) that responds to both `.decode` and `.encode` at the class level.
 
 MultiJSON tries to have intelligent defaulting. That is, if you have any of the
 supported engines already loaded, it will utilize them before attempting to
-load any. When loading, libraries are ordered by speed. First Yajl-Ruby, then
-the JSON gem, then JSON pure. If no JSON library is available, MultiJSON falls
-back to a bundled version of [OkJson][].
+load any. When loading, libraries are ordered by speed. First Oj, then Yajl,
+then the JSON gem, then JSON pure. If no other JSON library is available,
+MultiJSON falls back to [OkJson][], a simple, vendorable JSON parser.
 
 [okjson]: https://github.com/kr/okjson
 
 ## Supported JSON Engines
 
-* [`:yajl`](https://github.com/brianmario/yajl-ruby) Yet another json library, C extension
-* [`:json_gem`](https://github.com/genki/json) Json gem as C extension
-* [`:json_pure`](https://github.com/genki/json) Pure ruby implementation of the json gem
-* [`:ok_json`][okjson] Pure ruby implementation, aiming for maximum compatibility
-* [`:nsjsonserialization`](https://developer.apple.com/library/ios/#documentation/Foundation/Reference/NSJSONSerialization_Class/Reference/Reference.html) Wrapper for Apple's NSJSONSerialization out of the Cocoa Framework (MacRuby only)
+* [Oj](https://github.com/ohler55/oj) Optimized JSON by Peter Ohler
+* [Yajl](https://github.com/brianmario/yajl-ruby) Yet Another JSON Library by Brian Lopez
+* [JSON](https://github.com/flori/json) The default JSON gem with C-extensions (ships with Ruby 1.9)
+* [JSON Pure](https://github.com/flori/json) A Ruby variant of the JSON gem
+* [NSJSONSerialization](https://developer.apple.com/library/ios/#documentation/Foundation/Reference/NSJSONSerialization_Class/Reference/Reference.html) Wrapper for Apple's NSJSONSerialization in the Cocoa Framework (MacRuby only)
+* [OkJson][okjson] A simple, vendorable JSON parser
 
 ## <a name="contributing"></a>Contributing
 In the spirit of [free software][free-sw], **everyone** is encouraged to help

data/lib/multi_json.rb

@@ -20,6 +20,7 @@ module MultiJson
   end
 
   REQUIREMENT_MAP = [
+    ["oj", :oj],
     ["yajl", :yajl],
     ["json", :json_gem],
     ["json/pure", :json_pure]
@@ -32,6 +33,7 @@ module MultiJson
   # if any engines are already loaded, then checks
   # to see which are installed if none are loaded.
   def default_engine
+    return :oj if defined?(::Oj)
     return :yajl if defined?(::Yajl)
     return :json_gem if defined?(::JSON)
 

data/lib/multi_json/engines/json_common.rb

@@ -2,26 +2,26 @@ module MultiJson
   module Engines
     module JsonCommon
 
-      def decode(string, options = {})
+      def decode(string, options={})
         opts = {}
         opts[:symbolize_names] = options[:symbolize_keys]
         string = string.read if string.respond_to?(:read)
         ::JSON.parse(string, opts)
       end
 
-      def encode(object, options = {})
+      def encode(object, options={})
         object.to_json(process_options(options))
       end
 
-      protected
+    protected
 
-        def process_options(options={})
-          return options if options.empty?
-          opts = {}
-          opts.merge!(JSON::PRETTY_STATE_PROTOTYPE.to_h) if options.delete(:pretty)
-          opts.merge! options
-        end
+      def process_options(options={})
+        return options if options.empty?
+        opts = {}
+        opts.merge!(JSON::PRETTY_STATE_PROTOTYPE.to_h) if options.delete(:pretty)
+        opts.merge! options
+      end
 
     end
   end
-end
+end

data/lib/multi_json/engines/nsjsonserialization.rb

@@ -5,7 +5,7 @@ module MultiJson
   module Engines
     class Nsjsonserialization < MultiJson::Engines::OkJson
       ParseError = ::MultiJson::OkJson::Error
-      
+
       def self.decode(string, options = {})
         string = string.read if string.respond_to?(:read)
         data = string.dataUsingEncoding(NSUTF8StringEncoding)
@@ -28,7 +28,7 @@ module MultiJson
           super(object, options)
         end
       end
-      
+
     end
   end
 end

data/lib/multi_json/engines/oj.rb

@@ -0,0 +1,22 @@
+require 'oj' unless defined?(::Oj)
+
+::Oj.default_options = {:mode => :compat}
+
+module MultiJson
+  module Engines
+    # Use the Oj library to encode/decode.
+    class Oj
+      ParseError = SyntaxError
+
+      def self.decode(string, options = {}) #:nodoc:
+        opts = {}
+        opts[:symbol_keys] = options[:symbolize_keys]
+        ::Oj.load(string, opts)
+      end
+
+      def self.encode(object, options = {}) #:nodoc:
+        ::Oj.dump(object, options)
+      end
+    end
+  end
+end

data/lib/multi_json/engines/ok_json.rb

@@ -1,4 +1,4 @@
-require "multi_json/vendor/ok_json"
+require 'multi_json/vendor/ok_json'
 
 module MultiJson
   module Engines

data/lib/multi_json/engines/yajl.rb

@@ -1,4 +1,4 @@
-require 'yajl' unless defined?(Yajl)
+require 'yajl' unless defined?(::Yajl)
 
 module MultiJson
   module Engines

data/lib/multi_json/vendor/ok_json.rb

@@ -584,4 +584,4 @@ module MultiJson
     Unesc = {?b=>?\b, ?f=>?\f, ?n=>?\n, ?r=>?\r, ?t=>?\t}
     Hex = '0123456789abcdef'
   end
-end
+end

data/lib/multi_json/version.rb

@@ -1,3 +1,3 @@
 module MultiJson
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/multi_json.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rspec', '~> 2.6'
   gem.add_development_dependency 'simplecov', '~> 0.4'
   gem.authors = ["Michael Bleigh", "Josh Kalderimis", "Erik Michaels-Ober"]
-  gem.description = %q{A gem to provide swappable JSON backends utilizing Yajl::Ruby, the JSON gem, JSON pure, or a vendored version of okjson.}
+  gem.description = %q{A gem to provide easy switching between different JSON backends, including Oj, Yajl, the JSON gem (with C-extensions), the pure-Ruby JSON gem, and OkJson.}
   gem.email = ['michael@intridea.com', 'josh.kalderimis@gmail.com', 'sferik@gmail.com']
   gem.extra_rdoc_files = ['LICENSE.md', 'README.md']
   gem.files = Dir['LICENSE.md', 'README.md', 'Rakefile', 'multi_json.gemspec', 'Gemfile', '.document', '.rspec', '.travis.yml' ,'spec/**/*', 'lib/**/*']

data/spec/engine_shared_example.rb

@@ -0,0 +1,115 @@
+shared_examples_for "an engine" do |engine|
+
+  before do
+    begin
+      MultiJson.engine = engine
+    rescue LoadError
+      pending "Engine #{engine} couldn't be loaded (not installed?)"
+    end
+  end
+
+  describe '.encode' do
+    it 'writes decodable JSON' do
+      [
+        {'abc' => 'def'},
+        [1, 2, 3, "4"],
+      ].each do |example|
+        MultiJson.decode(MultiJson.encode(example)).should == example
+      end
+    end
+
+    it 'encodes symbol keys as strings' do
+      [
+        [
+          {:foo => {:bar => 'baz'}},
+          {'foo' => {'bar' => 'baz'}},
+        ],
+        [
+          [{:foo => {:bar => 'baz'}}],
+          [{'foo' => {'bar' => 'baz'}}],
+        ],
+        [
+          {:foo => [{:bar => 'baz'}]},
+          {'foo' => [{'bar' => 'baz'}]},
+        ]
+      ].each do |example, expected|
+        encoded_json = MultiJson.encode(example)
+        MultiJson.decode(encoded_json).should == expected
+      end
+    end
+
+    it 'encodes rootless JSON' do
+      MultiJson.encode("random rootless string").should == "\"random rootless string\""
+      MultiJson.encode(123).should == "123"
+    end
+
+    it 'passes options to the engine' do
+      MultiJson.engine.should_receive(:encode).with('foo', {:bar => :baz})
+      MultiJson.encode('foo', :bar => :baz)
+    end
+
+    if engine == 'json_gem' || engine == 'json_pure'
+      describe 'with :pretty option set to true' do
+        it 'passes default pretty options' do
+          object = 'foo'
+          object.should_receive(:to_json).with(JSON::PRETTY_STATE_PROTOTYPE.to_h)
+          MultiJson.encode(object,:pretty => true)
+        end
+      end
+    end
+
+    it "encodes custom objects which implement as_json" do
+      MultiJson.encode(TimeWithZone.new).should == "\"2005-02-01T15:15:10Z\""
+    end
+  end
+
+  describe '.decode' do
+    it 'properly decodes valid JSON' do
+      MultiJson.decode('{"abc":"def"}').should == {'abc' => 'def'}
+    end
+
+    it 'raises MultiJson::DecodeError on invalid JSON' do
+      lambda do
+        MultiJson.decode('{"abc"}')
+      end.should raise_error(MultiJson::DecodeError)
+    end
+
+    it 'raises MultiJson::DecodeError with data on invalid JSON' do
+      data = '{invalid}'
+      begin
+        MultiJson.decode(data)
+      rescue MultiJson::DecodeError => de
+        de.data.should == data
+      end
+    end
+
+    it 'stringifys symbol keys when encoding' do
+      encoded_json = MultiJson.encode(:a => 1, :b => {:c => 2})
+      MultiJson.decode(encoded_json).should == {"a" => 1, "b" => {"c" => 2}}
+    end
+
+    it "properly decodes valid JSON in StringIOs" do
+      json = StringIO.new('{"abc":"def"}')
+      MultiJson.decode(json).should == {'abc' => 'def'}
+    end
+
+    it 'allows for symbolization of keys' do
+      [
+        [
+          '{"abc":{"def":"hgi"}}',
+          {:abc => {:def => 'hgi'}},
+        ],
+        [
+          '[{"abc":{"def":"hgi"}}]',
+          [{:abc => {:def => 'hgi'}}],
+        ],
+        [
+          '{"abc":[{"def":"hgi"}]}',
+          {:abc => [{:def => 'hgi'}]},
+        ],
+      ].each do |example, expected|
+        MultiJson.decode(example, :symbolize_keys => true).should == expected
+      end
+    end
+  end
+end

data/spec/helper.rb

@@ -1,9 +1,15 @@
+def jruby?
+  defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
+end
+
 def macruby?
   defined?(RUBY_ENGINE) && RUBY_ENGINE == 'macruby'
 end
 
-require 'simplecov'
-SimpleCov.start unless macruby?
+unless ENV['CI'] || macruby?
+  require 'simplecov'
+  SimpleCov.start
+end
 require 'multi_json'
 require 'rspec'
 
@@ -22,15 +28,3 @@ class TimeWithZone
     "\"2005-02-01T15:15:10Z\""
   end
 end
-
-def yajl_on_travis(engine)
-  ENV['TRAVIS'] && engine == 'yajl' && jruby?
-end
-
-def nsjsonserialization_on_other_than_macruby(engine)
-  engine == 'nsjsonserialization' && !macruby?
-end
-
-def jruby?
-  defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
-end

data/spec/multi_json_spec.rb

@@ -1,7 +1,8 @@
 require 'helper'
+require 'engine_shared_example'
 require 'stringio'
 
-describe "MultiJson" do
+describe 'MultiJson' do
   context 'engines' do
     before do
       MultiJson.engine = nil
@@ -9,21 +10,24 @@ describe "MultiJson" do
     context 'when no other json implementations are available' do
       before do
         @old_map = MultiJson::REQUIREMENT_MAP
-        @old_yajl = Object.const_get :Yajl if Object.const_defined?(:Yajl)
         @old_json = Object.const_get :JSON if Object.const_defined?(:JSON)
+        @old_oj = Object.const_get :Oj if Object.const_defined?(:Oj)
+        @old_yajl = Object.const_get :Yajl if Object.const_defined?(:Yajl)
         MultiJson::REQUIREMENT_MAP.each_with_index do |(library, engine), index|
           MultiJson::REQUIREMENT_MAP[index] = ["foo/#{library}", engine]
         end
-        Object.send :remove_const, :Yajl if @old_yajl
         Object.send :remove_const, :JSON if @old_json
+        Object.send :remove_const, :Oj if @old_oj
+        Object.send :remove_const, :Yajl if @old_yajl
       end
 
       after do
         @old_map.each_with_index do |(library, engine), index|
           MultiJson::REQUIREMENT_MAP[index] = [library, engine]
         end
-        Object.const_set :Yajl, @old_yajl if @old_yajl
         Object.const_set :JSON, @old_json if @old_json
+        Object.const_set :Oj, @old_oj if @old_oj
+        Object.const_set :Yajl, @old_yajl if @old_yajl
       end
 
       it 'defaults to ok_json if no other json implementions are available' do
@@ -38,8 +42,8 @@ describe "MultiJson" do
 
     it 'defaults to the best available gem' do
       unless jruby?
-        require 'yajl'
-        MultiJson.engine.name.should == 'MultiJson::Engines::Yajl'
+        require 'oj'
+        MultiJson.engine.name.should == 'MultiJson::Engines::Oj'
       else
         require 'json'
         MultiJson.engine.name.should == 'MultiJson::Engines::JsonGem'
@@ -57,129 +61,12 @@ describe "MultiJson" do
     end
   end
 
-  %w(json_gem json_pure ok_json yajl nsjsonserialization).each do |engine|
-    if yajl_on_travis(engine)
-      puts "Yajl with JRuby is not tested on Travis as C-exts are turned off due to there experimental nature"
-      next
-    end
-    if nsjsonserialization_on_other_than_macruby(engine)
-      puts "NSJSONSerialization is exclusively available for MacRuby only."
-      next
-    end
+  %w(json_gem json_pure nsjsonserialization oj ok_json yajl).each do |engine|
+    next if !macruby? && engine == 'nsjsonserialization'
+    next if jruby? && (engine == 'oj' || engine == 'yajl')
 
     context engine do
-      before do
-        begin
-          MultiJson.engine = engine
-        rescue LoadError
-          pending "Engine #{engine} couldn't be loaded (not installed?)"
-        end
-      end
-
-      describe '.encode' do
-        it 'writes decodable JSON' do
-          [
-            { 'abc' => 'def' },
-            [1, 2, 3, "4"]
-          ].each do |example|
-            MultiJson.decode(MultiJson.encode(example)).should == example
-          end
-        end
-
-        it 'encodes symbol keys as strings' do
-          [
-            [
-              { :foo => { :bar => 'baz' } },
-              { 'foo' => { 'bar' => 'baz' } }
-            ],
-            [
-              [ { :foo => { :bar => 'baz' } } ],
-              [ { 'foo' => { 'bar' => 'baz' } } ],
-            ],
-            [
-              { :foo => [ { :bar => 'baz' } ] },
-              { 'foo' => [ { 'bar' => 'baz' } ] },
-            ]
-          ].each do |example, expected|
-            encoded_json = MultiJson.encode(example)
-            MultiJson.decode(encoded_json).should == expected
-          end
-        end
-
-        it 'encodes rootless JSON' do
-          MultiJson.encode("random rootless string").should == "\"random rootless string\""
-          MultiJson.encode(123).should == "123"
-        end
-
-        it 'passes options to the engine' do
-          MultiJson.engine.should_receive(:encode).with('foo', {:bar => :baz})
-          MultiJson.encode('foo', :bar => :baz)
-        end
-
-        if engine == 'json_gem' || engine == 'json_pure'
-          describe 'with :pretty option set to true' do
-            it 'passes default pretty options' do
-              object = 'foo'
-              object.should_receive(:to_json).with(JSON::PRETTY_STATE_PROTOTYPE.to_h)
-              MultiJson.encode(object,:pretty => true)
-            end
-          end
-        end
-
-        it "encodes custom objects which implement as_json" do
-          MultiJson.encode(TimeWithZone.new).should == "\"2005-02-01T15:15:10Z\""
-        end
-      end
-
-      describe '.decode' do
-        it 'properly decodes valid JSON' do
-          MultiJson.decode('{"abc":"def"}').should == { 'abc' => 'def' }
-        end
-
-        it 'raises MultiJson::DecodeError on invalid JSON' do
-          lambda do
-            MultiJson.decode('{"abc"}')
-          end.should raise_error(MultiJson::DecodeError)
-        end
-
-        it 'raises MultiJson::DecodeError with data on invalid JSON' do
-          data = '{invalid}'
-          begin
-            MultiJson.decode(data)
-          rescue MultiJson::DecodeError => de
-            de.data.should == data
-          end
-        end
-
-        it 'stringifys symbol keys when encoding' do
-          encoded_json = MultiJson.encode(:a => 1, :b => {:c => 2})
-          MultiJson.decode(encoded_json).should == { "a" => 1, "b" => { "c" => 2 } }
-        end
-
-        it "properly decodes valid JSON in StringIOs" do
-          json = StringIO.new('{"abc":"def"}')
-          MultiJson.decode(json).should == { 'abc' => 'def' }
-        end
-
-        it 'allows for symbolization of keys' do
-          [
-            [
-              '{"abc":{"def":"hgi"}}',
-              { :abc => { :def => 'hgi' } }
-            ],
-            [
-              '[{"abc":{"def":"hgi"}}]',
-              [ { :abc => { :def => 'hgi' } } ]
-            ],
-            [
-              '{"abc":[{"def":"hgi"}]}',
-              { :abc => [ { :def => 'hgi' } ] }
-            ],
-          ].each do |example, expected|
-            MultiJson.decode(example, :symbolize_keys => true).should == expected
-          end
-        end
-      end
+      it_should_behave_like "an engine", engine
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: multi_json
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-18 00:00:00.000000000 Z
+date: 2012-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70295944803660 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -23,10 +23,15 @@ dependencies:
         version: '0.9'
   type: :development
   prerelease: false
-  version_requirements: *70295944803660
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70295944803060 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -34,10 +39,15 @@ dependencies:
         version: '3.9'
   type: :development
   prerelease: false
-  version_requirements: *70295944803060
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70295944802460 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -45,10 +55,15 @@ dependencies:
         version: '2.6'
   type: :development
   prerelease: false
-  version_requirements: *70295944802460
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70295944801920 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -56,9 +71,14 @@ dependencies:
         version: '0.4'
   type: :development
   prerelease: false
-  version_requirements: *70295944801920
-description: A gem to provide swappable JSON backends utilizing Yajl::Ruby, the JSON
-  gem, JSON pure, or a vendored version of okjson.
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: A gem to provide easy switching between different JSON backends, including
+  Oj, Yajl, the JSON gem (with C-extensions), the pure-Ruby JSON gem, and OkJson.
 email:
 - michael@intridea.com
 - josh.kalderimis@gmail.com
@@ -77,12 +97,14 @@ files:
 - .document
 - .rspec
 - .travis.yml
+- spec/engine_shared_example.rb
 - spec/helper.rb
 - spec/multi_json_spec.rb
 - lib/multi_json/engines/json_common.rb
 - lib/multi_json/engines/json_gem.rb
 - lib/multi_json/engines/json_pure.rb
 - lib/multi_json/engines/nsjsonserialization.rb
+- lib/multi_json/engines/oj.rb
 - lib/multi_json/engines/ok_json.rb
 - lib/multi_json/engines/yajl.rb
 - lib/multi_json/vendor/ok_json.rb
@@ -109,11 +131,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
 summary: A gem to provide swappable JSON backends.
 test_files:
+- spec/engine_shared_example.rb
 - spec/helper.rb
 - spec/multi_json_spec.rb
 has_rdoc: