Merge pull request #1044 from rnubel/documentation

Increase documentation coverage

Author: dblock

lib/grape/api.rb

@@ -1,47 +1,60 @@
 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 = []
         @routes = nil
         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 @@ def inherit_settings(other_settings)
       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 @@ def initialize
       @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 @@ def add_head_not_allowed_methods_and_options_methods
       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 @@ def without_versioning(&_block)
       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)
 

lib/grape/dsl/callbacks.rb

@@ -2,24 +2,44 @@
 
 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

lib/grape/dsl/configuration.rb

@@ -10,6 +10,9 @@ module ClassMethods
 
         include Grape::DSL::Settings
 
+        # Set or retrive the configured logger. If none was configured, this
+        # method will create a new one, logging to stdout.
+        # @param logger [Object] the new logger to use
         def logger(logger = nil)
           if logger
             global_setting(:logger, logger)
@@ -19,6 +22,39 @@ def logger(logger = nil)
         end
 
         # Add a description to the next namespace or function.
+        # @param description [String] descriptive string for this endpoint
+        #   or namespace
+        # @param options [Hash] other properties you can set to describe the
+        #   endpoint or namespace. Optional.
+        # @option options :detail [String] additional detail about this endpoint
+        # @option options :params [Hash] param types and info. normally, you set
+        #   these via the `params` dsl method.
+        # @option options :entity [Grape::Entity] the entity returned upon a
+        #   successful call to this action
+        # @option options :http_codes [Array[Array]] possible HTTP codes this
+        #   endpoint may return, with their meanings, in a 2d array
+        # @option options :named [String] a specific name to help find this route
+        # @option options :headers [Hash] HTTP headers this method can accept
+        # @yield a block yielding an instance context with methods mapping to
+        #   each of the above, except that :entity is also aliased as #success
+        #   and :http_codes is aliased as #failure.
+        #
+        # @example
+        #
+        #     desc 'create a user'
+        #     post '/users' do
+        #       # ...
+        #     end
+        #
+        #     desc 'find a user' do
+        #       detail 'locates the user from the given user ID'
+        #       failure [ [404, 'Couldn\'t find the given user' ] ]
+        #       success User::Entity
+        #     end
+        #     get '/user/:id' do
+        #       # ...
+        #     end
+        #
         def desc(description, options = {}, &config_block)
           if block_given?
             config_class = Grape::DSL::Configuration.desc_container
@@ -40,11 +76,13 @@ def desc(description, options = {}, &config_block)
 
       module_function
 
+      # Merge multiple layers of settings into one hash.
       def stacked_hash_to_hash(settings)
         return nil if settings.nil? || settings.blank?
         settings.each_with_object(ActiveSupport::OrderedHash.new) { |value, result| result.deep_merge!(value) }
       end
 
+      # Returns an object which configures itself via an instance-context DSL.
       def desc_container
         Module.new do
           include Grape::Util::StrictHashConfiguration.module(

lib/grape/dsl/inside_route.rb

@@ -238,6 +238,14 @@ def route
         env['rack.routing_args'][:route_info]
       end
 
+      # Attempt to locate the Entity class for a given object, if not given
+      # explicitly. This is done by looking for the presence of Klass::Entity,
+      # where Klass is the class of the `object` parameter, or one of its
+      # ancestors.
+      # @param object [Object] the object to locate the Entity class for
+      # @param options [Hash]
+      # @option options :with [Class] the explicit entity class to use
+      # @return [Class] the located Entity class, or nil if none is found
       def entity_class_for_obj(object, options)
         entity_class = options.delete(:with)
 
@@ -259,6 +267,8 @@ def entity_class_for_obj(object, options)
         entity_class
       end
 
+      # @return the representation of the given object as done through
+      #   the given entity_class.
       def entity_representation_for(entity_class, object, options)
         embeds = { env: env }
         embeds[:version] = env['api.version'] if env['api.version']

lib/grape/dsl/parameters.rb

@@ -2,6 +2,9 @@
 
 module Grape
   module DSL
+    # Defines DSL methods, meant to be applied to a ParamsScope, which define
+    # and describe the parameters accepted by an endpoint, or all endpoints
+    # within a namespace.
     module Parameters
       extend ActiveSupport::Concern
 
@@ -39,6 +42,47 @@ def use(*names)
       alias_method :use_scope, :use
       alias_method :includes, :use
 
+      # Require one or more parameters for the current endpoint.
+      #
+      # @param attrs list of parameter names, or, if :using is
+      #   passed as an option, which keys to include (:all or :none) from
+      #   the :using hash. The last key can be a hash, which specifies
+      #   options for the parameters
+      # @option attrs :type [Class] the type to coerce this parameter to before
+      #   passing it to the endpoint. See Grape::ParameterTypes for supported
+      #   types, or use a class that defines `::parse` as a custom type
+      # @option attrs :desc [String] description to document this parameter
+      # @option attrs :default [Object] default value, if parameter is optional
+      # @option attrs :values [Array] permissable values for this field. If any
+      #   other value is given, it will be handled as a validation error
+      # @option attrs :using [Hash[Symbol => Hash]] a hash defining keys and
+      #   options, like that returned by Grape::Entity#documentation. The value
+      #   of each key is an options hash accepting the same parameters
+      # @option attrs :except [Array[Symbol]] a list of keys to exclude from
+      #   the :using Hash. The meaning of this depends on if :all or :none was
+      #   passed; :all + :except will make the :except fields optional, whereas
+      #   :none + :except will make the :except fields required
+      #
+      # @example
+      #
+      #     params do
+      #       # Basic usage: require a parameter of a certain type
+      #       requires :user_id, type: Integer
+      #
+      #       # You don't need to specify type; String is default
+      #       requires :foo
+      #
+      #       # Multiple params can be specified at once if they share
+      #       # the same options.
+      #       requires :x, :y, :z, type: Date
+      #
+      #       # Nested parameters can be handled as hashes. You must
+      #       # pass in a block, within which you can use any of the
+      #       # parameters DSL methods.
+      #       requires :user, type: Hash do
+      #         requires :name, type: String
+      #       end
+      #     end
       def requires(*attrs, &block)
         orig_attrs = attrs.clone
 
@@ -55,6 +99,10 @@ def requires(*attrs, &block)
         end
       end
 
+      # Allow, but don't require, one or more parameters for the current
+      #   endpoint.
+      # @param (see #requires)
+      # @option (see #requires)
       def optional(*attrs, &block)
         orig_attrs = attrs.clone
 
@@ -77,24 +125,35 @@ def optional(*attrs, &block)
         end
       end
 
+      # Disallow the given parameters to be present in the same request.
+      # @param attrs [*Symbol] parameters to validate
       def mutually_exclusive(*attrs)
         validates(attrs, mutual_exclusion: true)
       end
 
+      # Require exactly one of the given parameters to be present.
+      # @param (see #mutually_exclusive)
       def exactly_one_of(*attrs)
         validates(attrs, exactly_one_of: true)
       end
 
+      # Require at least one of the given parameters to be present.
+      # @param (see #mutually_exclusive)
       def at_least_one_of(*attrs)
         validates(attrs, at_least_one_of: true)
       end
 
+      # Require that either all given params are present, or none are.
+      # @param (see #mutually_exclusive)
       def all_or_none_of(*attrs)
         validates(attrs, all_or_none_of: true)
       end
 
       alias_method :group, :requires
 
+      # @param params [Hash] initial hash of parameters
+      # @return hash of parameters relevant for the current scope
+      # @api private
       def params(params)
         params = @parent.params(params) if @parent
         if @element

lib/grape/dsl/routing.rb

@@ -135,6 +135,18 @@ def route(methods, paths = ['/'], route_options = {}, &block)
           end
         end
 
+        # Declare a "namespace", which prefixes all subordinate routes with its
+        # name. Any endpoints within a namespace, or group, resource, segment,
+        # etc., will share their parent context as well as any configuration
+        # done in the namespace context.
+        #
+        # @example
+        #
+        #     namespace :foo do
+        #       get 'bar' do
+        #         # defines the endpoint: GET /foo/bar
+        #       end
+        #     end
         def namespace(space = nil, options = {}, &block)
           if space || block_given?
             within_namespace do
@@ -162,6 +174,7 @@ def routes
           @routes ||= prepare_routes
         end
 
+        # Remove all defined routes.
         def reset_routes!
           @routes = nil
         end
@@ -177,6 +190,7 @@ def route_param(param, options = {}, &block)
           namespace(":#{param}", options, &block)
         end
 
+        # @return array of defined versions
         def versions
           @versions ||= []
         end