resubject 0.0.2 → 0.0.3

data/Gemfile

@@ -1,6 +1,7 @@
 source 'https://rubygems.org'
 
 gem 'rails', '~> 3.2.10'
+gem 'redcarpet'
 
 # Specify your gem's dependencies in resubject.gemspec
 gemspec

data/README.md

@@ -10,7 +10,7 @@ Uber simple presenters using Ruby's SimpleDelegator.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'resubject', '~> 0.0.2'
+gem 'resubject', '~> 0.0.3'
 ```
 
 And then execute:

data/Rakefile

@@ -1,8 +1,13 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yard'
 
 desc 'Default: run specs.'
 task :default => :spec
 
 desc 'Run all specs'
 RSpec::Core::RakeTask.new(:spec)
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end

data/lib/resubject/builder.rb

@@ -1,26 +1,36 @@
 module Resubject
   module Builder
-    class InvalidPresenterArgument < StandardError #:nodoc:
+    # Raised when a invalid presenter is received
+    class InvalidPresenterArgument < StandardError
     end
 
     # Presents a object or a collection of objects
     #
-    # Examples:
+    # @param [Object, Array<Object>] objects objects to be instantiated with related presenter
+    # @param template then HTML template context
+    # @param [Presenter] presenters one or multiple presenters
     #
-    #    Builder.present box, template
-    #    => <BoxPresenter>
+    # @return [Presenter, Array<Presenter>] either the presenter or a collection of presenter
     #
-    #    # Using a custom presenter
-    #    Builder.present box, template, CustomPresenter
-    #    => <CustomPresenter>
+    # @example
     #
-    #    # Using multiple presenters
-    #    Builder.present box, template, OnePresenter, CustomPresenter
-    #    => <OnePresenter<CustomPresenter>>
+    #   Builder.present box, template
+    #   # => <BoxPresenter>
     #
-    #    # Using a collection
-    #    Builder.present [box, box], template
-    #    => [<BoxPresenter>, <BoxPresenter>]
+    #   # Using a custom presenter
+    #   Builder.present box, template, CustomPresenter
+    #   # => <CustomPresenter>
+    #
+    #   # Using multiple presenters
+    #   Builder.present box, template, OnePresenter, CustomPresenter
+    #   # => <OnePresenter<CustomPresenter>>
+    #
+    #   # Using a collection
+    #   Builder.present [box, box], template
+    #   # => [<BoxPresenter>, <BoxPresenter>]
+    #
+    # @see .present_one
+    # @see .present_all
     #
     def self.present(objects, template, *presenters)
       if objects.respond_to?(:each)
@@ -32,10 +42,21 @@ module Resubject
 
     # Presents a single object (see .present)
     #
-    # Example:
+    # @param [Object] object object to be instantiated with related presenter
+    # @param template then HTML template context
+    # @param [Presenter] presenters one or multiple presenters
+    #
+    # @raise [InvalidPresenterArgument] if a presenter was not received in presenters param
+    #
+    # @return [Presenter] either instance of the presenter related to the object
     #
-    #    Builder.present box, template
-    #    => <BoxPresenter>
+    # @example
+    #
+    #   Builder.present_one box, context                              # => <BoxPresenter>
+    #   Builder.present_one box, context, CustomPresenter             # => <CustomPresenter>
+    #   Builder.present_one box, context, OnePresenter, TwoPresenter  # => <TwoPresenter<OnePresenter>>
+    #
+    # @see .present
     #
     def self.present_one(object, template, *presenters)
       presenters = [Naming.presenter_for(object)] unless presenters.any?
@@ -51,10 +72,19 @@ module Resubject
 
     # Presents a collection of objects (see .present)
     #
-    # Example:
+    # @param [Array<Object>] objects objects to be instantiated with related presenter
+    # @param template then HTML template context
+    # @param [Presenter] presenters one or multiple presenters
+    #
+    # @return [Array<Presenter>] collection of instances of the related presenter
+    #
+    # @example
+    #
+    #   Builder.present [box, box], template
+    #   # => [<BoxPresenter>, <BoxPresenter>]
     #
-    #    Builder.present [box, box], template
-    #    => [<BoxPresenter>, <BoxPresenter>]
+    # @see .present
+    # @see .present_one
     #
     def self.present_all(objects, template, *presenters)
       objects.map do |o|

data/lib/resubject/naming.rb

@@ -2,6 +2,16 @@ require 'active_support/core_ext/string/inflections'
 
 module Resubject
   module Naming
+    # Discover the presenter class given the class name or string/symbol passed
+    #
+    # @example
+    #
+    #   Naming.presenter_for :post     # => PostPresenter
+    #   Naming.presenter_for "post"    # => PostPresenter
+    #   Naming.presenter_for Post.new  # => PostPresenter
+    #
+    # @param [Object, String, Symbol] presentable the reference object
+    # @return [Presenter] the related presenter class based on the object
     def self.presenter_for(presentable)
       klass = case presentable
         when Symbol

data/lib/resubject/presenter.rb

@@ -2,9 +2,20 @@ require 'delegate'
 
 module Resubject
   class Presenter < SimpleDelegator
+    # the HTML helpers context
     attr_reader  :context
     alias_method :template, :context
 
+    # Create a new presenter
+    #
+    # @param model any object that can be presented
+    # @param context a context of HTML helpers
+    #
+    # @example
+    #
+    #   PostPresenter.new(post)
+    #   PostPresenter.new(post, view_context)
+    #
     def initialize(model, context = nil)
       @context = context
       super(model)
@@ -14,39 +25,50 @@ module Resubject
 
     # Builds a collection of presenters given an array of objects
     #
-    # Example:
+    # @param [Array<Object>] collection
+    # @param context the HTML helpers context
+    # @return [Array<Presenter>] instances of a presenter for each item in the collection
+    #
+    # @example
     #
     #   boxes = [box1, box2, box3]
     #   BoxPresenter.all boxes
     #   # => [<BoxPresenter>, <BoxPresenter>, <BoxPresenter>]
     #
+    #   PostPresenter.all Post.all
+    #   # => [<PostPresenter>, ...]
+    #
     def self.all(collection, context = nil)
       collection.map { |c| new(c, context) }
     end
 
     # Creates a presenter from object or collection of objects
-    # See Builder.present for more details
-    # Example:
     #
-    #    present box
-    #    => <BoxPresenter>
+    # @example
+    #
+    #   present box                          # => <BoxPresenter>
+    #   present [box, box]                   # => [<BoxPresenter>, <BoxPresenter>]
+    #   present [box, box], CustomPresenter  # => <CustomPresenter>
+    #
+    # @param [Object, Array<Object>] objects objects to be instantiated with related presenter
+    # @param [Presenter] presenters one or multiple presenters
+    # @return [Presenter, Array<Presenter>] either the presenter or a collection of presenter
     #
+    # @see Builder.present
     def present(objects, *presenters)
       Builder.present objects, context, *presenters
     end
 
     # Generates a instance method with the attribute presented
     #
-    # Example:
+    # @example
     #
-    #    class BoxPresenter < Resubject::Presenter
-    #      presents :name
-    #      # or
-    #      # presents :name, CustomPresenter
-    #    end
+    #   class BoxPresenter < Resubject::Presenter
+    #     presents :name
+    #     # or presents :name, CustomPresenter
+    #   end
     #
-    #    BoxPresenter.new(box).name
-    #    => <NamePresenter>
+    #   BoxPresenter.new(box).name   # => <NamePresenter>
     #
     def self.presents(attribute, *presenters)
       define_method attribute do

data/lib/resubject/rails/extensions.rb

@@ -1,25 +1,28 @@
 module Resubject
-  module Rails #:nodoc:
+  module Rails
+    # All Rails extensions
     module Extensions
       # Generates an attribute using `number_to_currency` helper from rails
       #
-      # Examples:
+      # @example
       #
-      #    class ProductPresenter < Resubject::Presenter
-      #      currency :price
-      #    end
+      #   class ProductPresenter < Resubject::Presenter
+      #     currency :price
+      #   end
       #
-      #    # Will create a `price` attribute using `number_to_currency`
+      #   # Will create a `price` attribute using `number_to_currency`
       #
-      #    product.price
-      #    # => '$10.00'
+      #   product.price
+      #   # => '$10.00'
       #
-      # Options:
+      # @example Also, any number_to_currency options are accepted
       #
-      #    currency :price, precision: 3   # => '$123.456'
-      #    currency :price, locale: :fr    # => '123,51 €'
+      #   currency :price, precision: 3   # => '$123.456'
+      #   currency :price, locale: :fr    # => '123,51 €'
       #
-      # See ActionView::Helpers::NumberHelper#number_to_currency[http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_to_currency] for other options
+      # @param [Symbol] attribute the name of the presented attribute to be generated
+      # @param [Hash] options the options for `number_to_currency` method
+      # @see http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_to_currency
       def currency(attribute, options = {})
         define_method attribute do
           template.number_to_currency to_model.send(attribute), options

data/lib/resubject/rails/helpers.rb

@@ -1,9 +1,15 @@
 module Resubject
+  # ActionController helpers
+  #
+  # In case you have Rails, these helpers will be automatically included
+  #
   module Helpers
-    def self.included(base) #:nodoc:
+    # adds present as a helper method in the controller
+    def self.included(base)
       base.send(:helper_method, :present)
     end
 
+    # @see Builder.present
     def present(objects, *presenters)
       presenters = Builder.present(objects, view_context, *presenters)
 

data/lib/resubject/version.rb

@@ -1,3 +1,3 @@
 module Resubject
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/resubject.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "rspec", "~> 2.12.0"
+  gem.add_development_dependency "yard", "~> 0.8.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resubject
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -60,6 +60,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 2.12.0
+- !ruby/object:Gem::Dependency
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+  name: yard
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.3
 description: Uber simple presenters
 email:
 - felipe@applicake.com
@@ -106,7 +122,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       segments:
       - 0
       version: '0'
-      hash: 134183276947229850
+      hash: 3846405687038123926
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -115,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       segments:
       - 0
       version: '0'
-      hash: 134183276947229850
+      hash: 3846405687038123926
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -128,3 +144,4 @@ test_files:
 - spec/resubject/presenter_spec.rb
 - spec/resubject/rails/extensions_spec.rb
 - spec/spec_helper.rb
+has_rdoc: