grape 0.12.0 → 0.13.0

data/CONTRIBUTING.md

@@ -1,16 +1,16 @@
 Contributing to Grape
 =====================
 
-Grape is work of [hundreds of contributors](https://github.com/intridea/grape/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/intridea/grape/pulls), [propose features and discuss issues](https://github.com/intridea/grape/issues). When in doubt, ask a question in the [Grape Google Group](http://groups.google.com/group/ruby-grape).
+Grape is work of [hundreds of contributors](https://github.com/ruby-grape/grape/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/ruby-grape/grape/pulls), [propose features and discuss issues](https://github.com/ruby-grape/grape/issues). When in doubt, ask a question in the [Grape Google Group](http://groups.google.com/group/ruby-grape).
 
 #### Fork the Project
 
-Fork the [project on Github](https://github.com/intridea/grape) and check out your copy.
+Fork the [project on Github](https://github.com/ruby-grape/grape) and check out your copy.
 
 ```
 git clone https://github.com/contributor/grape.git
 cd grape
-git remote add upstream https://github.com/intridea/grape.git
+git remote add upstream https://github.com/ruby-grape/grape.git
 ```
 
 #### Create a Topic Branch
@@ -102,7 +102,7 @@ git push origin my-feature-branch -f
 Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
 
 ```
-* [#123](https://github.com/intridea/grape/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
+* [#123](https://github.com/ruby-grape/grape/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
 ```
 
 Amend your previous commit and force push the changes.

data/README.md

@@ -1,10 +1,10 @@
 ![grape logo](grape.png)
 
 [![Gem Version](http://img.shields.io/gem/v/grape.svg)](http://badge.fury.io/rb/grape)
-[![Build Status](http://img.shields.io/travis/intridea/grape.svg)](https://travis-ci.org/intridea/grape)
-[![Dependency Status](https://gemnasium.com/intridea/grape.svg)](https://gemnasium.com/intridea/grape)
-[![Code Climate](https://codeclimate.com/github/intridea/grape.svg)](https://codeclimate.com/github/intridea/grape)
-[![Inline docs](http://inch-ci.org/github/intridea/grape.svg)](http://inch-ci.org/github/intridea/grape)
+[![Build Status](http://img.shields.io/travis/ruby-grape/grape.svg)](https://travis-ci.org/ruby-grape/grape)
+[![Dependency Status](https://gemnasium.com/ruby-grape/grape.svg)](https://gemnasium.com/ruby-grape/grape)
+[![Code Climate](https://codeclimate.com/github/ruby-grape/grape.svg)](https://codeclimate.com/github/ruby-grape/grape)
+[![Inline docs](http://inch-ci.org/github/ruby-grape/grape.svg)](http://inch-ci.org/github/ruby-grape/grape)
 
 ## Table of Contents
 
@@ -29,6 +29,9 @@
   - [Declared](#declared)
   - [Include Missing](#include-missing)
 - [Parameter Validation and Coercion](#parameter-validation-and-coercion)
+  - [Supported Parameter Types](#supported-parameter-types)
+  - [Custom Types](#custom-types)
+  - [Dependent Parameters](#dependent-parameters)
   - [Built-in Validators](#built-in-validators)
   - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
   - [Custom Validators](#custom-validators)
@@ -37,6 +40,7 @@
 - [Headers](#headers)
 - [Routes](#routes)
 - [Helpers](#helpers)
+- [Path Helpers](#path-helpers)
 - [Parameter Documentation](#parameter-documentation)
 - [Cookies](#cookies)
 - [HTTP Status Code](#http-status-code)
@@ -75,6 +79,8 @@
   - [Reloading in Rack Applications](#reloading-in-rack-applications)
   - [Reloading in Rails Applications](#reloading-in-rails-applications)
 - [Performance Monitoring](#performance-monitoring)
+  - [Active Support Instrumentation](#active-support-instrumentation)
+  - [Monitoring Products](#monitoring-products)
 - [Contributing to Grape](#contributing-to-grape)
 - [Hacking on Grape](#hacking-on-grape)
 - [License](#license)
@@ -90,13 +96,13 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape 0.12.0.
+You're reading the documentation for the stable release of Grape, 0.13.0.
 Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
 
+* [Grape Website](http://www.ruby-grape.org)
 * Need help? [Grape Google Group](http://groups.google.com/group/ruby-grape)
-* [Grape Wiki](https://github.com/intridea/grape/wiki)
 
 ## Installation
 
@@ -729,6 +735,54 @@ params do
 end
 ```
 
+#### Supported Parameter Types
+
+The following are all valid types, supported out of the box by Grape:
+
+* Integer
+* Float
+* BigDecimal
+* Numeric
+* Date
+* DateTime
+* Time
+* Boolean
+* String
+* Symbol
+* Rack::Multipart::UploadedFile
+
+#### Custom Types
+
+Aside from the default set of supported types listed above, any class can be
+used as a type so long as it defines a class-level `parse` method. This method
+must take one string argument and return an instance of the correct type, or
+raise an exception to indicate the value was invalid. E.g.,
+
+```ruby
+class Color
+  attr_reader :value
+  def initialize(color)
+    @value = color
+  end
+
+  def self.parse(value)
+    fail 'Invalid color' unless %w(blue red green).include?(value)
+    new(value)
+  end
+end
+
+# ...
+
+params do
+  requires :color, type: Color, default: Color.new('blue')
+end
+
+get '/stuff' do
+  # params[:color] is already a Color.
+  params[:color].value
+end
+```
+
 #### Validation of Nested Parameters
 
 Parameters can be nested using `group` or by calling `requires` or `optional` with a block.
@@ -752,6 +806,21 @@ params do
 end
 ```
 
+#### Dependent Parameters
+
+Suppose some of your parameters are only relevant if another parameter is given;
+Grape allows you to express this relationship through the `given` method in your
+parameters block, like so:
+
+```ruby
+params do
+  optional :shelf_id, type: Integer
+  given :shelf_id do
+    requires :bin_id, type: Integer
+  end
+end
+```
+
 ### Built-in Validators
 
 #### `allow_blank`
@@ -1034,6 +1103,16 @@ subject.rescue_from Grape::Exceptions::ValidationErrors do |e|
 end
 ```
 
+`Grape::Exceptions::ValidationErrors#full_messages` returns the validation messages as an array. `Grape::Exceptions::ValidationErrors#message` joins the messages to one string.
+
+For responding with an array of validation messages, you can use `Grape::Exceptions::ValidationErrors#full_messages`.
+```ruby
+format :json
+subject.rescue_from Grape::Exceptions::ValidationErrors do |e|
+  error!({ messages: e.full_messages }, 400)
+end
+```
+
 ### I18n
 
 Grape supports I18n for parameter-related error messages, but will fallback to English if
@@ -1198,6 +1277,10 @@ class API < Grape::API
 end
 ```
 
+## Path Helpers
+
+If you need methods for generating paths inside your endpoints, please see the [grape-route-helpers](https://github.com/reprah/grape-route-helpers) gem.
+
 ## Parameter Documentation
 
 You can attach additional documentation to `params` using a `documentation` hash.
@@ -1339,7 +1422,7 @@ instead of a message.
 error!({ error: "unexpected error", detail: "missing widget" }, 500)
 ```
 
-You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/intridea/grape-entity) gem.
+You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
 
 ```ruby
 module API
@@ -1860,8 +1943,8 @@ hash may include `:with`, which defines the entity to expose.
 
 ### Grape Entities
 
-Add the [grape-entity](https://github.com/intridea/grape-entity) gem to your Gemfile.
-Please refer to the [grape-entity documentation](https://github.com/intridea/grape-entity/blob/master/README.md)
+Add the [grape-entity](https://github.com/ruby-grape/grape-entity) gem to your Gemfile.
+Please refer to the [grape-entity documentation](https://github.com/ruby-grape/grape-entity/blob/master/README.md)
 for more details.
 
 The following example exposes statuses.
@@ -2023,6 +2106,8 @@ end
 Use `body false` to return `204 No Content` without any data or content-type.
 
 You can also set the response to a file-like object with `file`.
+Note: Rack will read your entire Enumerable before returning a response. If
+you would like to stream the response, see `stream`.
 
 ```ruby
 class FileStreamer
@@ -2044,6 +2129,16 @@ class API < Grape::API
 end
 ```
 
+If you want a file-like object to be streamed using Rack::Chunked, use `stream`.
+
+```ruby
+class API < Grape::API
+  get '/' do
+    stream FileStreamer.new('file.bin')
+  end
+end
+```
+
 ## Authentication
 
 ### Basic and Digest Auth
@@ -2534,6 +2629,34 @@ See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-
 
 ## Performance Monitoring
 
+### Active Support Instrumentation
+
+Grape has built-in support for [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) which provides simple hook points to instrument key parts of your application.
+
+The following are currently supported:
+
+#### endpoint_run.grape
+
+The main execution of an endpoint, includes filters and rendering.
+
+* *endpoint* - The endpoint instance
+
+#### endpoint_render.grape
+
+The execution of the main content block of the endpoint.
+
+* *endpoint* - The endpoint instance
+
+#### endpoint_run_filters.grape
+
+* *endpoint* - The endpoint instance
+* *filters* - The filters being executed
+* *type* - The type of filters (before, before_validation, after_validation, after)
+
+See the [ActiveSupport::Notifications documentation](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html] for information on how to subscribe to these events.
+
+### Monitoring Products
+
 Grape integrates with NewRelic via the
 [newrelic-grape](https://github.com/flyerhzm/newrelic-grape) gem, and
 with Librato Metrics with the [grape-librato](https://github.com/seanmoon/grape-librato) gem.
@@ -2550,7 +2673,7 @@ See [CONTRIBUTING](CONTRIBUTING.md).
 You can start hacking on Grape on
 [Nitrous.IO](https://www.nitrous.io/?utm_source=github.com&utm_campaign=grape&utm_medium=hackonnitrous) in a matter of seconds:
 
-[![Hack intridea/grape on Nitrous.IO](https://d3o0mnbgv6k92a.cloudfront.net/assets/hack-l-v1-3cc067e71372f6045e1949af9d96095b.png)](https://www.nitrous.io/hack_button?source=embed&runtime=rails&repo=intridea%2Fgrape&file_to_open=README.md)
+[![Hack ruby-grape/grape on Nitrous.IO](https://d3o0mnbgv6k92a.cloudfront.net/assets/hack-l-v1-3cc067e71372f6045e1949af9d96095b.png)](https://www.nitrous.io/hack_button?source=embed&runtime=rails&repo=intridea%2Fgrape&file_to_open=README.md)
 
 ## License
 

data/RELEASING.md

@@ -12,12 +12,12 @@ bundle install
 rake
 ```
 
-Check that the last build succeeded in [Travis CI](https://travis-ci.org/intridea/grape) for all supported platforms.
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/ruby-grape/grape) for all supported platforms.
 
-Those with r/w permissions to the [master Intridea repository](https://github.com/intridea/grape) generally have large Grape-based projects. Point one to Grape HEAD and run all your API tests to catch any obvious regressions.
+Those with r/w permissions to the [master Grape repository](https://github.com/ruby-grape/grape) generally have large Grape-based projects. Point one to Grape HEAD and run all your API tests to catch any obvious regressions.
 
 ```
-gem grape, github: 'intridea/grape'
+gem grape, github: 'ruby-grape/grape'
 ```
 
 Increment the version, modify [lib/grape/version.rb](lib/grape/version.rb).
@@ -69,7 +69,7 @@ Modify the "Stable Release" section in [README.md](README.md). Change the text t
 ## Stable Release
 
 You're reading the documentation for the next release of Grape, which should be 0.6.1.
-The current stable release is [0.6.0](https://github.com/intridea/grape/blob/v0.6.0/README.md).
+The current stable release is [0.6.0](https://github.com/ruby-grape/grape/blob/v0.6.0/README.md).
 ```
 
 Add the next release to [CHANGELOG.md](CHANGELOG.md).
@@ -81,11 +81,19 @@ Next Release
 * Your contribution here.
 ```
 
+Bump the minor version in lib/grape/version.rb.
+
+```ruby
+module Grape
+  VERSION = '0.6.1'
+end
+```
+
 Comit your changes.
 
 ```
-git add CHANGELOG.md README.md
-git commit -m "Preparing for next release."
+git add CHANGELOG.md README.md lib/grape/version.rb
+git commit -m "Preparing for next development iteration, 0.6.1."
 git push origin master
 ```
 

data/Rakefile

@@ -44,7 +44,7 @@ begin
           Dir.mkdir(dir)
           Dir.chdir(dir) do
             system('git init')
-            system('git remote add origin git@github.com:intridea/grape.git')
+            system('git remote add origin git@github.com:ruby-grape/grape.git')
             system('git pull')
             system('git checkout gh-pages')
           end

data/UPGRADING.md

@@ -29,13 +29,13 @@ class CacheBusterMiddleware < Grape::Middleware::Base
 end
 ```
 
-See [#1029](https://github.com/intridea/grape/pull/1029) for more information.
+See [#1029](https://github.com/ruby-grape/grape/pull/1029) for more information.
 
 #### Changes in present
 
 Using `present` with objects that responded to `merge` would cause early evaluation of the represented object, with unexpected side-effects, such as missing parameters or environment within rendering code. Grape now only merges represented objects with a previously rendered body, usually when multiple `present` calls are made in the same route.
 
-See [grape-with-roar#5](https://github.com/dblock/grape-with-roar/issues/5) and [#1023](https://github.com/intridea/grape/issues/1023).
+See [grape-with-roar#5](https://github.com/dblock/grape-with-roar/issues/5) and [#1023](https://github.com/ruby-grape/grape/issues/1023).
 
 #### Changes to regexp validator
 
@@ -47,7 +47,7 @@ params do
 end
 ```
 
-See [#957](https://github.com/intridea/grape/pull/957) for more information.
+See [#957](https://github.com/ruby-grape/grape/pull/957) for more information.
 
 #### Replace error_response with error! in rescue_from blocks
 
@@ -88,11 +88,11 @@ Rack::Response.new([ e.message ], 500, { "Content-type" => "text/error" }).finis
 error!(e)
 ```
 
-See [#889](https://github.com/intridea/grape/issues/889) for more information.
+See [#889](https://github.com/ruby-grape/grape/issues/889) for more information.
 
 #### Changes to routes when using `format`
 
-Version 0.10.0 has introduced a change via [#809](https://github.com/intridea/grape/pull/809) whereas routes no longer got file-type suffixes added if you declared a single API `format`. This has been reverted, it's now again possible to call API with proper suffix when single `format` is defined:
+Version 0.10.0 has introduced a change via [#809](https://github.com/ruby-grape/grape/pull/809) whereas routes no longer got file-type suffixes added if you declared a single API `format`. This has been reverted, it's now again possible to call API with proper suffix when single `format` is defined:
 
 ```ruby
 class API < Grape::API
@@ -108,7 +108,7 @@ Will respond with JSON to `/hello` **and** `/hello.json`.
 
 Will respond with 404 to `/hello.xml`, `/hello.txt` etc.
 
-See the [#1001](https://github.com/intridea/grape/pull/1001) and [#914](https://github.com/intridea/grape/issues/914) for more info.
+See the [#1001](https://github.com/ruby-grape/grape/pull/1001) and [#914](https://github.com/ruby-grape/grape/issues/914) for more info.
 
 ### Upgrading to >= 0.11.0
 
@@ -120,20 +120,20 @@ Grape now supports, but doesn't require Rack 1.6.0. If you encounter an issue wi
 gem 'rack', '~> 1.6.0'
 ```
 
-See [#559](https://github.com/intridea/grape/issues/559) for more information.
+See [#559](https://github.com/ruby-grape/grape/issues/559) for more information.
 
 #### Removed route_info
 
 Key route_info is excluded from params.
 
-See [#879](https://github.com/intridea/grape/pull/879) for more information.
+See [#879](https://github.com/ruby-grape/grape/pull/879) for more information.
 
 
 #### Fix callbacks within a version block
 
 Callbacks defined in a version block are only called for the routes defined in that block. This was a regression introduced in Grape 0.10.0, and is fixed in this version.
 
-See [#901](https://github.com/intridea/grape/pull/901) for more information.
+See [#901](https://github.com/ruby-grape/grape/pull/901) for more information.
 
 
 #### Make type of group of parameters required
@@ -141,7 +141,7 @@ See [#901](https://github.com/intridea/grape/pull/901) for more information.
 Groups of parameters now require their type to be set explicitly as Array or Hash.
 Not setting the type now results in MissingGroupTypeError, unsupported type will raise UnsupportedTypeError.
 
-See [#886](https://github.com/intridea/grape/pull/886) for more information.
+See [#886](https://github.com/ruby-grape/grape/pull/886) for more information.
 
 ### Upgrading to >= 0.10.1
 
@@ -149,7 +149,7 @@ See [#886](https://github.com/intridea/grape/pull/886) for more information.
 
 Attributes with `nil` values or with values that evaluate to `false` are no longer considered *missing* and will be returned when `include_missing` is set to `false`.
 
-See [#864](https://github.com/intridea/grape/pull/864) for more information.
+See [#864](https://github.com/ruby-grape/grape/pull/864) for more information.
 
 ### Upgrading to >= 0.10.0
 
@@ -284,13 +284,13 @@ get do
 end
 ```
 
-For more information see [#836](https://github.com/intridea/grape/issues/836).
+For more information see [#836](https://github.com/ruby-grape/grape/issues/836).
 
 #### Changes to Custom Validators
 
 To implement a custom validator, you need to inherit from `Grape::Validations::Base` instead of `Grape::Validations::Validator`.
 
-For more information see [Custom Validators](https://github.com/intridea/grape#custom-validators) in the documentation.
+For more information see [Custom Validators](https://github.com/ruby-grape/grape#custom-validators) in the documentation.
 
 #### Changes to Raising Grape::Exceptions::Validation
 
@@ -337,7 +337,7 @@ class API < Grape::API
 end
 ```
 
-See the [the updated API Formats documentation](https://github.com/intridea/grape#api-formats) and [#809](https://github.com/intridea/grape/pull/809) for more info.
+See the [the updated API Formats documentation](https://github.com/ruby-grape/grape#api-formats) and [#809](https://github.com/ruby-grape/grape/pull/809) for more info.
 
 #### Changes to Evaluation of Permitted Parameter Values
 
@@ -357,7 +357,7 @@ params do
 end
 ```
 
-See [#801](https://github.com/intridea/grape/issues/801) for more information.
+See [#801](https://github.com/ruby-grape/grape/issues/801) for more information.
 
 #### Changes to version
 
@@ -389,7 +389,7 @@ end
 
 when making a API call `GET /foo/v2/1`, the API would set instance variable `@output` to `hello1-v2`
 
-See [#898](https://github.com/intridea/grape/issues/898) for more information.
+See [#898](https://github.com/ruby-grape/grape/issues/898) for more information.
 
 
 ### Upgrading to >= 0.9.0
@@ -422,10 +422,10 @@ As replacement can be used
 * `Grape::Middleware::Auth::Digest` => [`Rack::Auth::Digest::MD5`](https://github.com/rack/rack/blob/master/lib/rack/auth/digest/md5.rb)
 * `Grape::Middleware::Auth::OAuth2` => [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2)
 
-If this is not possible you can extract the middleware files from [grape v0.7.0](https://github.com/intridea/grape/tree/v0.7.0/lib/grape/middleware/auth)
+If this is not possible you can extract the middleware files from [grape v0.7.0](https://github.com/ruby-grape/grape/tree/v0.7.0/lib/grape/middleware/auth)
 and host these files within your application
 
-See [#703](https://github.com/intridea/Grape/pull/703) for more information.
+See [#703](https://github.com/ruby-grape/Grape/pull/703) for more information.
 
 ### Upgrading to >= 0.7.0
 
@@ -462,7 +462,7 @@ rescue_from ParentError, rescue_subclasses: false do |e|
 end
 ```
 
-See [#544](https://github.com/intridea/grape/pull/544) for more information.
+See [#544](https://github.com/ruby-grape/grape/pull/544) for more information.
 
 
 #### Changes in the Default HTTP Status Code
@@ -485,7 +485,7 @@ You may also use `default_error_status` to change the global default.
 default_error_status 400
 ```
 
-See [#525](https://github.com/intridea/Grape/pull/525) for more information.
+See [#525](https://github.com/ruby-grape/Grape/pull/525) for more information.
 
 
 #### Changes in Parameter Declaration and Validation
@@ -502,7 +502,7 @@ params do
 end
 ```
 
-This caused the ambiguity and unexpected errors described in [#543](https://github.com/intridea/Grape/issues/543).
+This caused the ambiguity and unexpected errors described in [#543](https://github.com/ruby-grape/Grape/issues/543).
 
 In Grape 0.7.0, the `group`, `optional` and `requires` keywords take an additional `type` attribute which defaults to `Array`. This means that without a `type` attribute, these nested parameters will no longer accept a single hash, only an array (of hashes).
 
@@ -530,7 +530,7 @@ params do
 end
 ```
 
-See [#545](https://github.com/intridea/Grape/pull/545) for more information.
+See [#545](https://github.com/ruby-grape/Grape/pull/545) for more information.
 
 
 ### Upgrading to 0.6.0
@@ -547,4 +547,4 @@ rescue_from Grape::Exceptions::Validations do |e|
 end
 ```
 
-For more information see [#462](https://github.com/intridea/grape/issues/462).
+For more information see [#462](https://github.com/ruby-grape/grape/issues/462).

data/grape.gemspec

@@ -7,13 +7,11 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ['Michael Bleigh']
   s.email       = ['michael@intridea.com']
-  s.homepage    = 'https://github.com/intridea/grape'
+  s.homepage    = 'https://github.com/ruby-grape/grape'
   s.summary     = 'A simple Ruby framework for building REST-like APIs.'
   s.description = 'A Ruby framework for rapid API development with great conventions.'
   s.license     = 'MIT'
 
-  s.rubyforge_project = 'grape'
-
   s.add_runtime_dependency 'rack', '>= 1.3.0'
   s.add_runtime_dependency 'rack-mount'
   s.add_runtime_dependency 'rack-accept'

data/lib/grape/api.rb

@@ -1,14 +1,17 @@
 module Grape
-  # The API class is the primary entry point for
-  # creating Grape APIs.Users should subclass this
-  # class in order to build an API.
+  # The API class is the primary entry point for creating Grape APIs. Users
+  # should subclass this class in order to build an API.
   class API
     include Grape::DSL::API
 
     class << self
       attr_reader :instance
+
+      # A class-level lock to ensure the API is not compiled by multiple
+      # threads simultaneously within the same process.
       LOCK = Mutex.new
 
+      # Clears all defined routes, endpoints, etc., on this API.
       def reset!
         @route_set = Rack::Mount::RouteSet.new
         @endpoints = []
@@ -16,32 +19,42 @@ module Grape
         reset_validations!
       end
 
+      # Parses the API's definition and compiles it into an instance of
+      # Grape::API.
       def compile
         @instance ||= new
       end
 
+      # Wipe the compiled API so we can recompile after changes were made.
       def change!
         @instance = nil
       end
 
+      # This is the interface point between Rack and Grape; it accepts a request
+      # from Rack and ultimately returns an array of three values: the status,
+      # the headers, and the body. See [the rack specification]
+      # (http://www.rubydoc.info/github/rack/rack/master/file/SPEC) for more.
       def call(env)
         LOCK.synchronize { compile } unless instance
         call!(env)
       end
 
+      # A non-synchronized version of ::call.
       def call!(env)
         instance.call(env)
       end
 
       # Create a scope without affecting the URL.
       #
-      # @param name [Symbol] Purely placebo, just allows to name the scope to make the code more readable.
+      # @param _name [Symbol] Purely placebo, just allows to name the scope to
+      # make the code more readable.
       def scope(_name = nil, &block)
         within_namespace do
           nest(block)
         end
       end
 
+      # (see #cascade?)
       def cascade(value = nil)
         if value.nil?
           inheritable_setting.namespace_inheritable.keys.include?(:cascade) ? !!namespace_inheritable(:cascade) : true
@@ -84,6 +97,8 @@ module Grape
       end
     end
 
+    # Builds the routes from the defined endpoints, effectively compiling
+    # this API into a usable form.
     def initialize
       @route_set = Rack::Mount::RouteSet.new
       add_head_not_allowed_methods_and_options_methods
@@ -94,6 +109,7 @@ module Grape
       @route_set.freeze
     end
 
+    # Handle a request. See Rack documentation for what `env` is.
     def call(env)
       result = @route_set.call(env)
       result[1].delete(Grape::Http::Headers::X_CASCADE) unless cascade?
@@ -168,6 +184,8 @@ module Grape
       end
     end
 
+    # Allows definition of endpoints that ignore the versioning configuration
+    # used by the rest of your API.
     def without_versioning(&_block)
       old_version = self.class.namespace_inheritable(:version)
       old_version_options = self.class.namespace_inheritable(:version_options)
@@ -181,6 +199,8 @@ module Grape
       self.class.namespace_inheritable(:version_options, old_version_options)
     end
 
+    # Allows definition of endpoints that ignore the root prefix used by the
+    # rest of your API.
     def without_root_prefix(&_block)
       old_prefix = self.class.namespace_inheritable(:root_prefix)
 

data/lib/grape/dsl/callbacks.rb

@@ -2,24 +2,44 @@ require 'active_support/concern'
 
 module Grape
   module DSL
+    # Blocks can be executed before or after every API call, using `before`, `after`,
+    # `before_validation` and `after_validation`.
+    #
+    # Before and after callbacks execute in the following order:
+    #
+    # 1. `before`
+    # 2. `before_validation`
+    # 3. _validations_
+    # 4. `after_validation`
+    # 5. _the API call_
+    # 6. `after`
+    #
+    # Steps 4, 5 and 6 only happen if validation succeeds.
     module Callbacks
       extend ActiveSupport::Concern
 
       include Grape::DSL::Configuration
 
       module ClassMethods
+        # Execute the given block before validation, coercion, or any endpoint
+        # code is executed.
         def before(&block)
           namespace_stackable(:befores, block)
         end
 
+        # Execute the given block after `before`, but prior to validation or
+        # coercion.
         def before_validation(&block)
           namespace_stackable(:before_validations, block)
         end
 
+        # Execute the given block after validations and coercions, but before
+        # any endpoint code.
         def after_validation(&block)
           namespace_stackable(:after_validations, block)
         end
 
+        # Execute the given block after the endpoint code has run.
         def after(&block)
           namespace_stackable(:afters, block)
         end