Improve documentation

lib/hawk/linker.rb

@@ -1,7 +1,7 @@
 module Hawk
   # Allows adding to any Ruby object an accessor referencing an {Hawk::Model}.
   #
-  # Example, assuming Bar is defined and Foo responds_to `bar_id`:
+  # Example, assuming Bar is defined and Foo responds_to +bar_id+:
   #
   #     class Foo
   #       include Hawk::Linker

lib/hawk/model/association.rb

@@ -94,7 +94,6 @@ def inherited(subclass)
         # Example (for Joe :-)
         #
         #     class Foo < Hawk::Model::Base
-        #
         #       has_many :bars
         #
         #       preload_association do |attributes, name, type, options|
@@ -105,11 +104,10 @@ def inherited(subclass)
         #           end
         #         end
         #       end
-        #
         #     end
         #
-        # The block would get called once, with :bars as `name`, :has_many as
-        # `type` and `{class_name:'Bar', primary_key:'foo_id'}` as `options`.
+        # The block would get called once, with :bars as +name+, :has_many as
+        # +type+ and +{ class_name: "Bar", primary_key : "foo_id" }+ as +options+.
         #
         # By default it looks up in the representation a property named after
         # the association's name and returns it, deleting it from the repr.

lib/hawk/model/lookup.rb

@@ -38,13 +38,13 @@ def inherited(subclass)
         #
         #   App::Post.model_class_for('Comment')
         #
-        # will return `App::Comment`
+        # will return +App::Comment+
         #
         # while
         #
         #   Client::Post.model_class_for('Comment')
         #
-        # will return `Client::Comment`
+        # will return +Client::Comment+
         #
         # In a nutshell, first the model namespace is checked,
         # then the containing namespace, and then the inheritance

lib/hawk/model/querying.rb

@@ -33,13 +33,13 @@ def default_params(params = nil)
           @_default_params ||= {}
         end
 
-        # Adds `limit` with the given number of records
+        # Adds +limit+ with the given number of records
         #
         def limit(n)
           where(limit_param => n)
         end
 
-        # Adds an `offset` with the given number of records
+        # Adds an +offset+ with the given number of records
         #
         def offset(n)
           where(offset_param => n)

lib/hawk/rake/utils.rb

@@ -9,7 +9,6 @@ module Utils
       ##
       # Captures the stdout emitted by the given +block+
       #
-      # @param block [Proc]
       # @return [String] the captured output
       #
       def capture_stdout