Module: ActionAnnotation::Annotations::ClassMethods

Defined in:
lib/action_annotation/annotations.rb

Overview

This module contains methods for defining descriptions.

Syntax of descriptions

A description always contains an action, which is executed, and optionally a resource type and a source for the resource, on which the action is performed.

A description is specified as a string of the form

ACTION (* RESOURCE)? ((in|from|by) SOURCE)?

and will be transformed into a corrsponding hash.

At any point, comments can be inserted using brackets.

Examples

  • ‘show’ – { :action => :show }

  • ‘show comment’ – { :action => :show, :resource => :comment }

  • ‘shows all comments’ – { :action => :show, :resource => :comment }

  • ‘(if necessary) show all new comments (of this user)’ – { :action => :show, :resource => :comment }

  • ‘show a comment by :id’ – { :action => :show, :resource => :comment, :source => :id }

  • ‘show all comments in @comments’ – { :action => :show, :resource => :comment, :source => ‘@comments’ }

Notice that verbs a transformed into infinitive and resources are singularized. Unless the source starts with a colon, it will be provided as string

Defining descriptions

To add an description to a method, use #describe or #desc.

Also notice that adding new descriptions at runtime is not possible, once #descriptions_of was called.

Instance Method Summary collapse

Instance Method Details

#desc(*descriptions) ⇒ Object

Adds descriptions to the method that will be defined next.

  • descriptions list of description strings

Example

desc "shows a comment"
def show
  @comment = Comment.find(params[:id])
end



93
94
95
 
# File 'lib/action_annotation/annotations.rb', line 93

def desc(*descriptions)
  unassigned_descriptions.push(*descriptions)
end

#describe(method, *descriptions) ⇒ Object

Adds descriptions to a method.

  • method symbol or string

  • descriptions list of description strings

Example

describe :show, "shows a comment"
def show
  @comment = Comment.find(params[:id])
end



80
81
82
 
# File 'lib/action_annotation/annotations.rb', line 80

def describe(method, *descriptions)
  plain_descriptions_of(method).push(*descriptions)
end

#describe!(method, *descriptions) ⇒ Object

Adds descriptions to a method, but raises an argument error if the method was already described.

  • method symbol or string

  • descriptions list of description strings



65
66
67
68
 
# File 'lib/action_annotation/annotations.rb', line 65

def describe!(method, *descriptions)
  raise_if_already_described! method
  describe method, *descriptions
end

#descriptions_of(method) ⇒ Object

Returns the descriptions that were added to a method, returns an empty array if no descriptions were provided.

  • method symbol or string

Example

desc "shows a comment"
def show
  @comment = Comment.find(params[:id])
end

descriptions_of(:show) # == { :action => :show, :resource => :comment }



123
124
125
 
# File 'lib/action_annotation/annotations.rb', line 123

def descriptions_of(method)
  parsed_descriptions[method.to_sym]
end

#method_added(method) ⇒ Object

This module uses the method_added callback. If this method is overwritten and not called using super, desc will not work.



55
56
57
58
 
# File 'lib/action_annotation/annotations.rb', line 55

def method_added(method)
  check_pending_descriptions(method)
  super(method)
end

#parsed_descriptions ⇒ Object

:nodoc:



127
128
129
130
131
 
# File 'lib/action_annotation/annotations.rb', line 127

def parsed_descriptions # :nodoc:
  @parsed_descriptions ||= Hash.new do |h,k|
    h[k] = parse_descriptions(k)
  end
end

#plain_descriptions ⇒ Object

:nodoc:



105
106
107
108
109
 
# File 'lib/action_annotation/annotations.rb', line 105

def plain_descriptions # :nodoc:
  @plain_descriptions ||= Hash.new do |h,k|
    h[k] = fetch_inherited(k)
  end
end

#plain_descriptions_of(method) ⇒ Object

Returns the description strings that were added to a method, returns an empty array if no descriptions were provided.

  • method symbol or string



101
102
103
 
# File 'lib/action_annotation/annotations.rb', line 101

def plain_descriptions_of(method)
  plain_descriptions[method.to_sym]
end