possibly improved docs

Author: Philip Champon

README.markdown

@@ -445,32 +445,34 @@ end
 
 ## Reusable Responses with Entities
 
-Entities are a simple and reusable means for converting Ruby objects to API responses.
+Entities are a reusable means for converting Ruby objects to API responses.
 Entities can be used to conditionally include fields, nest other entities, and build
 ever larger responses, using inheritance.
 
 ### Defining Entities
 
-Entities inherit from Grape::Entity, and define a simple DSL. The `#expose` method can be called in 
-a number of ways. When processing options passed to exposures two keys will always be defined, :version
-and :collection. The :version key is define as api.version. The :collection key is boolean, and defined
-as true if the object presented is an array.
+Entities inherit from Grape::Entity, and define a simple DSL. Exposures can use
+runtime options to determine which fields should be visible, these options are
+available to :if, :unless, and :proc. The option keys :version and :collection
+will always be defined. The :version key is defined as api.version. The
+:collection key is boolean, and defined as true if the object presented is an
+array.
 
-  * expose SYMBOLS
+  * `expose SYMBOLS`
     * define a list of fields which will always be exposed
-  * expose SYMBOLS, HASH
+  * `expose SYMBOLS, HASH`
     * HASH keys include :if, :unless, :proc, :as, :using, :format_with, :documentation
       * :if and :unless accept hashes (passed during runtime) or procs (arguments are object and options)
-  * expose SYMBOL, {:format_with => :formatter}
+  * `expose SYMBOL, {:format_with => :formatter}`
     * expose a value, formatting it first
-    * `:format_with` can only be applied to one exposure at a time
-  * expose SYMBOL, {:as => "alias"}
+    * :format_with can only be applied to one exposure at a time
+  * `expose SYMBOL, {:as => "alias"}`
     * Expose a value, changing its hash key from SYMBOL to alias
-    * `:as` can only be applied to one exposure at a time
-  * expose SYMBOL BLOCK
+    * :as can only be applied to one exposure at a time
+  * `expose SYMBOL BLOCK`
     * block arguments are object and options
     * expose the value returned by the block
-    * `block` can only be applied to one exposure at a time
+    * block can only be applied to one exposure at a time
 
 ``` ruby
 module API

lib/grape/entity.rb

@@ -3,14 +3,16 @@
 module Grape
   # An Entity is a lightweight structure that allows you to easily
   # represent data from your application in a consistent and abstracted
-  # way in your API.
+  # way in your API. Entities can also provide documentation for the
+  # fields exposed.
   #
   # @example Entity Definition
   #
   #   module API
   #     module Entities
   #       class User < Grape::Entity
   #         expose :first_name, :last_name, :screen_name, :location
+  #         expose :field, :documentation => {:type => "string", :desc => "describe the field"}
   #         expose :latest_status, :using => API::Status, :as => :status, :unless => {:collection => true}
   #         expose :email, :if => {:type => :full}
   #         expose :new_attribute, :if => {:version => 'v2'}
@@ -30,6 +32,7 @@ module Grape
   #     class Users < Grape::API
   #       version 'v2'
   #
+  #       desc 'User index', { :object_fields => API::Entities::User.documentation }
   #       get '/users' do
   #         @users = User.all
   #         type = current_user.admin? ? :full : :default
@@ -63,11 +66,8 @@ class Entity
     #   will be called with the represented object as well as the
     #   runtime options that were passed in. You can also just supply a
     #   block to the expose call to achieve the same effect.
-    # @option options :documentation Provide documenation for an exposed 
+    # @option options :documentation Define documenation for an exposed 
     #   field, typically the value is a hash with two fields, type and desc. 
-    #   Call the class or instance method #documentation for use with #desc. 
-    #   When calling #docmentation, any exposure without a documentation key 
-    #   will be ignored.
     def self.expose(*args, &block)
       options = args.last.is_a?(Hash) ? args.pop : {}
 
@@ -98,9 +98,9 @@ def self.exposures
       @exposures
     end
 
-    # Returns a hash of documentation hashes that have been declared for this Entity or ancestors. The keys
-    # are symbolized references to fields in the response, the values are those defined in the 
-    # Entity's documentation key.
+    # Returns a hash, the keys are symbolized references to fields in the entity, 
+    # the values are document keys in the entity's documentation key. When calling 
+    # #docmentation, any exposure without a documentation key will be ignored.
     def self.documentation
       @documentation ||= exposures.inject({}) do |memo, value|
                            unless value[1][:documentation].nil? || value[1][:documentation].empty?