guard-opal-rails 0.1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b146594f065fa51c85b92c3d0c8d7f21ec50a295
+  data.tar.gz: 74d94ff26daccf2af6f03ada444835f03e9fc3ce
+SHA512:
+  metadata.gz: 8fd6c3402aaafac3a7b0a8818593b6d16b5c02f4f03fac3401cbc9d004bda145ddca08abd227c0cc0abfc95b10a50f054405cf38f14cee5e37f15c2567a15463
+  data.tar.gz: 9038f3bc2f842b4a9917615c72042635f5c9397510cd3f3ef40963a986c0a01e568a05ed1d46ab31e687e1ef93154a70c5338edc023e0666ac7696f3c0d069c8

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -0,0 +1,35 @@
+# This configuration was generated by `rubocop --auto-gen-config`
+# on 2015-03-09 12:47:55 -0700 using RuboCop version 0.29.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 9
+# Configuration parameters: AllowURI, URISchemes.
+Metrics/LineLength:
+  Max: 180
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/BracesAroundHashParameters:
+  Enabled: false
+
+# Offense count: 4
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/HashSyntax:
+  Enabled: false
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: SupportedStyles.
+Style/LambdaCall:
+  EnforcedStyle: braces
+
+# Offense count: 4
+# Configuration parameters: MaxSlashes.
+Style/RegexpLiteral:
+  Enabled: false
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in guard-opal-rails.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,28 @@
+group :specs, halt_on_fail: true do
+  guard :rspec, cmd: 'bundle exec rspec' do
+    require 'guard/rspec/dsl'
+    dsl = Guard::RSpec::Dsl.new(self)
+
+    # RSpec files
+    rspec = dsl.rspec
+    watch(rspec.spec_files)
+    watch(rspec.spec_helper) { rspec.spec_dir }
+    watch(rspec.spec_support) { rspec.spec_dir }
+
+    # Ruby files
+    dsl.watch_spec_files_for(dsl.ruby.lib_files)
+
+    watch(%r{^(lib/guard/rspec/template)s/Guardfile$}) do
+      rspec.spec.('lib/guard/rspec/template')
+    end
+
+    watch(%r{^lib/guard/rspec/dsl.rb$}) do
+      rspec.spec.('lib/guard/rspec/template')
+    end
+  end
+
+  guard :rubocop, all_on_start: false do
+    watch(%r{.+\.rb$})
+    watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Forrest Chang
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# Guard::OpalRails
+
+
+Guard::OpalRails automatically launches specs when files are modified.  For fast spec runs, it does not use the ```rake opal:spec``` task.
+
+
+## Installation
+
+Add this line to your application's Gemfile (inside the development group):
+
+```ruby
+gem 'guard-opal-rails'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install guard-opal-rails
+
+Add the guard definition to your Guardfile by running this command:
+
+```
+$ guard init opal-rails
+```
+
+## Usage
+
+Please read [Guard usage doc](https://github.com/guard/guard#readme).
+
+### List of available options:
+
+``` ruby
+spec_url: nil            # The url to hit to run the specs. Point to your_rails_app/opal_spec
+                         # or don't set/set to nil to use standalone server
+sound_on: true           # set to false to turn off, works w/osx terminal-notifier
+success_sound: "default" # Sound played with successful specs I use a custom applause sound
+fail_sound: "Sosumi      # Sound played with failed specs, defaults to "Sosumi"
+
+```
+
+## Notes
+
+### spec_url and how to run the spec server
+To run specs, this plugin hits the url specified in spec_url (your_rails_app/opal_spec) or kicks off the standalone spec server defined in opal-rails 0.7.1 and higher (at time of writing you may have to point to my opal-rails fork github.com/fkchang/opal-rails to get this feature.  So which server should you use? Some considerations
+
+#### Reasons to point to your own rails app
+
+* You're already running your rails app, and don't want the standalone server as yet another process to run.
+* You run something like pow, your app is always available
+* You run Windows or JRuby, the current implementation of the standalone spec server uses fork (not supported on windows MRI or Jruby) to daemonize the process
+* You need to run opal-rails specs in > that 1 project at once, currently the spec server is fixed to startup on localhost:9998
+
+#### Reasons to use the standalone spec server
+* Your app isn't always running
+* You only need to run opal-rails specs in one project at a time
+
+### Notifications
+
+The notifications sounds were built and tested around OSX's terminal notifier. Apologies to users of other notification plugins. Additions welcome.
+
+* Default sounds for success/fail were picked on sounds that ought to exist in OSX defaults (System Preferences > Sound > Sound Effects), I personally use much more dramatic custom sounds to good effect (make sme happy)
+* Clicking on notification will take you to the spec url page - handy on getting more details on a spec fail
+
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/guard-opal-rails/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+### Author
+
+[Forrest Chang](https://github.com/fkchang) ([@fkchang2000](https://twitter.com/fkchang2000))
+
+### Contributors
+
+[https://github.com/guard/guard-opal-rails/contributors](https://github.com/guard/guard-opal-rails/contributors)

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)

data/guard-opal-rails.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'guard/opal-rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'guard-opal-rails'
+  spec.version       = Guard::OpalRailsVersion::VERSION
+  spec.authors       = ['Forrest Chang']
+  spec.email         = ['fkc_email-ruby@yahoo.com']
+  spec.summary       = 'Guard gem for running specs in opal-rails'
+  spec.description   = 'Guard::OpalRails automatically runs your opal specs in rails projects using opal-rails'
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+  spec.add_dependency 'guard-compat', '~> 1.2'
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec'
+  # opal spec dir not configurable before this
+  spec.add_development_dependency 'opal-rails' # , '>= 0.7.1'
+  spec.add_development_dependency 'guard-rspec'
+  spec.add_development_dependency 'guard-rubocop'
+  spec.add_runtime_dependency 'opal-rails' # , ">= 0.7.1"
+end

data/lib/guard/opal-rails.rb

@@ -0,0 +1,132 @@
+# rubocop:disable all
+require 'guard/opal-rails/version'
+# rubocop:enable all
+require 'guard/compat/plugin'
+require 'guard/opal-rails/process_toggle_factory'
+
+module Guard
+  # The Guard plugin to run opal-rails specs
+  class OpalRails < Plugin
+    # the plugin states we care about
+
+    # Initializes a Guard plugin.
+    # Don't do any work here, especially as Guard plugins get initialized
+    # even if they are not in an active group!
+    #
+    # @param [Hash] options the custom Guard plugin options
+    # @option options [Array<Guard::Watcher>] watchers the Guard plugin file
+    #        watchers
+    # @option options [Symbol] group the group this Guard plugin belongs to
+    # @option options [Boolean] any_return allow any object to be returned from
+    #        a watcher
+    #
+    def initialize(options = {})
+      super
+      @process_toggle = ProcessToggleFactory.process_toggle_for options
+      @spec_url = @process_toggle.spec_url
+      @sounds_on = options[:sounds_on] == false ? false :  true
+      @success_sound = options[:success_sound] || 'default'
+      @fail_sound = options[:fail_sound] || 'Sosumi'
+    end
+    # Called once when Guard starts. Please override initialize method to init
+    # stuff.
+    #
+    # @raise [:task_has_failed] when start has failed
+    # @return [Object] the task result
+    #
+    def start
+      @process_toggle.start
+      run_opal_specs
+    end
+
+    # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
+    #
+    # @raise [:task_has_failed] when stop has failed
+    # @return [Object] the task result
+    #
+    def stop
+      @process_toggle.stop
+    end
+
+    # Called when just `enter` is pressed
+    # This method should be principally used for long action like running all
+    # specs/tests/...
+    #
+    # @raise [:task_has_failed] when run_all has failed
+    # @return [Object] the task result
+    #
+    def run_all
+      run_opal_specs
+    end
+
+    # Called on file(s) modifications that the Guard plugin watches.
+    #
+    # @param [Array<String>] paths the changes files or paths
+    # @raise [:task_has_failed] when run_on_modifications has failed
+    # @return [Object] the task result
+    #
+    # rubocop:disable all
+    def run_on_modifications(paths)
+    # rubocop:enable all
+
+      run_opal_specs
+    end
+
+    # learned this trick from guard-rails-assets because guard plugins don't
+    # expect to have hyphenated names
+    def self.template(plugin_location)
+      File.read(template_path(plugin_location))
+    end
+
+    def self.template_path(plugin_location)
+      # workaround because Guard discards the '-' when detecting template path
+      File.join(plugin_location, 'lib', 'guard', 'opal-rails', 'templates',
+                'Guardfile')
+    end
+
+    private
+
+    # this is the opal-rspec runner that uses phantomjs to hit your page
+    def spec_runner
+      @spec_runner ||= File.join(Gem::Specification.find_by_path('opal-rspec')
+                                  .full_gem_path,
+                                 '/vendor/spec_runner.js')
+    end
+
+    # Runs the specs, parses the output to give a notification
+
+    # rubocop:disable all
+    def run_opal_specs
+      results = `phantomjs #{spec_runner} #{@spec_url}`
+      puts results              # want this to show on the terminal
+      if results =~ /((\d+) examples, (\d+) failures .+\))/
+        message = $1
+        total = $2
+        failures = $3.to_i
+        if failures > 0
+          title = "#{failures} Specs failed"
+          sound = @fail_sound
+          image = :failed
+        else
+          title = "#{total} Specs passed"
+          sound = @success_sound
+          image = :success
+        end
+      else
+        message = results
+        title = 'Specs failed to run'
+        image = :failed
+        sound = @fail_sound
+      end
+      notify_params = {
+        type: image,
+        title: title,
+        open: @spec_url
+      }
+
+      notify_params.merge!(sound: sound) if @sounds_on
+      Guard::Compat::UI.notify(message, notify_params)
+    end
+    # rubocop:enable all
+  end
+end

data/lib/guard/opal-rails/null_process_toggle.rb

@@ -0,0 +1,18 @@
+require 'guard/opal-rails/process_toggle'
+
+module Guard
+  class OpalRails < Plugin
+    # Does nothing for start and stop
+    class NullProcessToggle < ProcessToggle
+      def spec_url
+        @options[:spec_url]
+      end
+
+      def start
+      end
+
+      def stop
+      end
+    end
+  end
+end

data/lib/guard/opal-rails/process_toggle.rb

@@ -0,0 +1,12 @@
+require 'guard/compat/plugin'
+module Guard
+  class OpalRails < Plugin
+    # Base class for process toggles.  These are classes which control
+    # start/stop for various situations
+    class ProcessToggle
+      def initialize(options = {})
+        @options = options
+      end
+    end
+  end
+end

data/lib/guard/opal-rails/process_toggle_factory.rb

@@ -0,0 +1,22 @@
+require_relative 'process_toggle'
+require_relative 'null_process_toggle'
+require_relative 'standalone_spec_server_process_toggle'
+require 'guard/compat/plugin'
+
+module Guard
+  class OpalRails < Plugin
+    # This class returns the correct type of ProcessToggle based on options
+    # currently there are 2 cases
+    # 1) url provided, so no processes need to be started
+    # 2) url not provided or nil, so se start up the standalong spec server
+    class ProcessToggleFactory
+      def self.process_toggle_for(options)
+        if options[:spec_url]
+          NullProcessToggle.new(options)
+        else
+          StandaloneSpecServerProcessToggle.new(options)
+        end
+      end
+    end
+  end
+end

data/lib/guard/opal-rails/standalone_spec_server_process_toggle.rb

@@ -0,0 +1,24 @@
+require 'guard/opal-rails/process_toggle'
+
+module Guard
+  class OpalRails < Plugin
+    # Starts and stops standalone spec server for opal-rails
+    class StandaloneSpecServerProcessToggle < ProcessToggle
+      include Rake::DSL if defined? Rake::DSL
+      # the url for specs, currently hard coded, anticipate dynamically
+      # retrieving this down the road.  Points to standlone spec server
+      # from opal-rails
+      def spec_url
+        'http://localhost:9998'
+      end
+
+      def start
+        system 'bundle exec rake opal:spec:start_server'
+      end
+
+      def stop
+        system 'bundle exec rake opal:spec:kill_server'
+      end
+    end
+  end
+end

data/lib/guard/opal-rails/templates/Guardfile

@@ -0,0 +1,10 @@
+# options for opal-rails - see README for more info
+# spec_url: The url to hit to run the specs. Point to your rails_app/opal_spec or don't set to run standalong server
+# sounds_on:  defaults to true set to false to turn off, works w/osx terminal-notifier
+# success_sound: Sound played with successful specs, defaults to "default". Needs to be in your OSX sound prefs
+# fail_sound: Sound played with failed specs, defaults to "Sosumi"
+guard 'opal-rails', :spec_url => 'your_rails_app/opal_spec', :sounds_on => true, :success_sound => 'applause', :fail_sound => 'submarine' do
+  # include where opal files and opal specs live, below are the defaults for
+  # opal-rails 0.7.1+
+  watch Regexp.new('(app/assets/javascripts|spec-opal)/.+\.rb')
+end

data/lib/guard/opal-rails/version.rb

@@ -0,0 +1,6 @@
+module Guard
+  # To store the version and not conflict w/plugin class name
+  module OpalRailsVersion
+    VERSION = '0.1.0.1'
+  end
+end

data/spec/lib/guard/opal-rails/process_toggle_factory_spec.rb

@@ -0,0 +1,20 @@
+require 'guard/opal-rails/process_toggle_factory'
+describe Guard::OpalRails::ProcessToggleFactory do
+  it 'should create NullProcessToggle for a specified spec_url' do
+    process_toggle = Guard::OpalRails::ProcessToggleFactory.process_toggle_for(
+      { spec_url: 'foo.dev/opal_spec' })
+    expect(process_toggle).to be_a Guard::OpalRails::NullProcessToggle
+  end
+
+  it 'should create StandaloneSpecServerProcessToggle for nil spec_url' do
+    process_toggle = Guard::OpalRails::ProcessToggleFactory.process_toggle_for(
+      { spec_url: nil })
+    expect(process_toggle).to be_a Guard::OpalRails::StandaloneSpecServerProcessToggle
+  end
+
+  it 'should return a StandaloneSpecServerProcessToggle if spec_url not defined' do
+    process_toggle = Guard::OpalRails::ProcessToggleFactory.process_toggle_for({})
+    expect(process_toggle).to be_a Guard::OpalRails::StandaloneSpecServerProcessToggle
+  end
+
+end

data/spec/lib/guard/opal-rails/standalone_spec_server_process_toggle_spec.rb

@@ -0,0 +1,13 @@
+require 'guard/opal-rails/standalone_spec_server_process_toggle'
+describe Guard::OpalRails::StandaloneSpecServerProcessToggle do
+  it 'should call the right rake task to start the server' do
+    # subject.should_receive(:run_task).with 'opal:spec:start_server'
+    expect(subject).to receive(:system).with 'bundle exec rake opal:spec:start_server'
+    subject.start
+  end
+  it 'should call the right rake task to stop the server' do
+    # subject.should_receive(:run_task).with 'opal:spec:kill_server'
+    expect(subject).to receive(:system).with 'bundle exec rake opal:spec:kill_server'
+    subject.stop
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: guard-opal-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0.1
+platform: ruby
+authors:
+- Forrest Chang
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: guard-compat
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: opal-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: opal-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Guard::OpalRails automatically runs your opal specs in rails projects
+  using opal-rails
+email:
+- fkc_email-ruby@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rubocop.yml
+- .rubocop_todo.yml
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- guard-opal-rails.gemspec
+- lib/guard/opal-rails.rb
+- lib/guard/opal-rails/null_process_toggle.rb
+- lib/guard/opal-rails/process_toggle.rb
+- lib/guard/opal-rails/process_toggle_factory.rb
+- lib/guard/opal-rails/standalone_spec_server_process_toggle.rb
+- lib/guard/opal-rails/templates/Guardfile
+- lib/guard/opal-rails/version.rb
+- spec/lib/guard/opal-rails/process_toggle_factory_spec.rb
+- spec/lib/guard/opal-rails/standalone_spec_server_process_toggle_spec.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: Guard gem for running specs in opal-rails
+test_files:
+- spec/lib/guard/opal-rails/process_toggle_factory_spec.rb
+- spec/lib/guard/opal-rails/standalone_spec_server_process_toggle_spec.rb
+has_rdoc: