merb-core 0.9.13 → 1.0

data/lib/merb-core/controller/merb_controller.rb

@@ -8,6 +8,7 @@ class Merb::Controller < Merb::AbstractController
   cattr_accessor :_subclasses
   self._subclasses = Set.new
 
+  # :api: private
   def self.subclasses_list() _subclasses end
 
   include Merb::ResponderMixin
@@ -19,7 +20,7 @@ class Merb::Controller < Merb::AbstractController
   # klass<Merb::Controller>::
   #   The Merb::Controller inheriting from the base class.
   #
-  # @api private
+  # :api: private
   def self.inherited(klass)
     _subclasses << klass.to_s
     super
@@ -35,7 +36,7 @@ class Merb::Controller < Merb::AbstractController
   # Array[String]::
   #   An array of actions that should not be possible to dispatch to.
   #
-  # @api public
+  # :api: public
   def self.hide_action(*names)
     self._hidden_actions = self._hidden_actions | names.map { |n| n.to_s }
   end
@@ -66,7 +67,7 @@ class Merb::Controller < Merb::AbstractController
   #     end
   #   end
   #
-  # @api public
+  # :api: public
   def self.show_action(*names)
     self._shown_actions = self._shown_actions | names.map {|n| n.to_s}
   end
@@ -78,7 +79,7 @@ class Merb::Controller < Merb::AbstractController
   # ==== Returns
   # SimpleSet[String]:: A set of actions that should be callable.
   #
-  # @api public
+  # :api: public
   def self.callable_actions
     @callable_actions ||= Extlib::SimpleSet.new(_callable_methods)
   end
@@ -91,7 +92,7 @@ class Merb::Controller < Merb::AbstractController
   # ==== Returns
   # Hash{Symbol => String}:: A new list of params, filtered as desired
   # 
-  # @api plugin
+  # :api: plugin
   # @overridable
   def self._filter_params(params)
     params
@@ -102,7 +103,7 @@ class Merb::Controller < Merb::AbstractController
   # ==== Returns
   # Array:: A list of method names that are also actions
   #
-  # @api private
+  # :api: private
   def self._callable_methods
     callables = []
     klass = self
@@ -129,7 +130,7 @@ class Merb::Controller < Merb::AbstractController
   # By default, this renders ":controller/:action.:type". To change this,
   # override it in your application class or in individual controllers.
   #
-  # @api public
+  # :api: public
   # @overridable
   def _template_location(context, type, controller)
     _conditionally_append_extension(controller ? "#{controller}/#{context}" : "#{context}", type)
@@ -147,7 +148,7 @@ class Merb::Controller < Merb::AbstractController
   # type<~to_s>::
   #    The mime-type of the template that will be rendered. Defaults to nil.
   #
-  # @api public
+  # :api: public
   def _absolute_template_location(template, type)
     _conditionally_append_extension(template, type)
   end
@@ -164,7 +165,7 @@ class Merb::Controller < Merb::AbstractController
   #   A hash of headers to start the controller with. These headers can be
   #   overridden later by the #headers method.
   # 
-  # @api plugin
+  # :api: plugin
   # @overridable
   def initialize(request, status=200, headers={'Content-Type' => 'text/html; charset=utf-8'})
     super()
@@ -182,7 +183,7 @@ class Merb::Controller < Merb::AbstractController
   # ==== Raises
   # ActionNotFound:: The requested action was not found in class.
   #
-  # @api plugin
+  # :api: plugin
   def _dispatch(action=:index)
     Merb.logger.info("Params: #{self.class._filter_params(request.params).inspect}")
     start = Time.now
@@ -195,12 +196,13 @@ class Merb::Controller < Merb::AbstractController
     self
   end
 
+  # :api: public
   attr_reader :request, :headers
 
   # ==== Returns
   # Fixnum:: The response status code
   #
-  # @api public
+  # :api: public
   def status
     @_status
   end
@@ -210,7 +212,7 @@ class Merb::Controller < Merb::AbstractController
   # ==== Parameters
   # s<Fixnum, Symbol>:: A status-code or named http-status
   #
-  # @api public
+  # :api: public
   def status=(s)
     if s.is_a?(Symbol) && STATUS_CODES.key?(s)
       @_status = STATUS_CODES[s]
@@ -224,7 +226,7 @@ class Merb::Controller < Merb::AbstractController
   # ==== Returns
   # Hash:: The parameters from the request object
   # 
-  # @api public
+  # :api: public
   def params()  request.params  end
     
   # There are three possible ways to use this method.  First, if you have a named route, 
@@ -280,7 +282,7 @@ class Merb::Controller < Merb::AbstractController
   #
   # url(:articles, 2008, 10, "test_article")
   #
-  # @api public
+  # :api: public
   def url(name, *args)
     args << params
     name = request.route if name == :this
@@ -315,7 +317,7 @@ class Merb::Controller < Merb::AbstractController
   # resource(:users, :new)      # => /users/new
   # resource(:@user, :edit)     # => /users/10/edit
   #
-  # @api public
+  # :api: public
   def resource(*args)
     args << params
     Merb::Router.resource(*args)
@@ -329,7 +331,7 @@ class Merb::Controller < Merb::AbstractController
   # This uses the same arguments as the url method, with added requirements 
   # of protocol and host options. 
   #
-  # @api public
+  # :api: public
   def absolute_url(*args)
     options  = extract_options_from_args!(args) || {}
     options[:protocol] ||= request.protocol
@@ -344,7 +346,7 @@ class Merb::Controller < Merb::AbstractController
   # Array[Integer, Hash, String]::
   #   The controller's status code, headers, and body
   #
-  # @api private
+  # :api: private
   def rack_response
     [status, headers, Merb::Rack::StreamWrapper.new(body)]
   end
@@ -353,7 +355,7 @@ class Merb::Controller < Merb::AbstractController
   # This controller will not be able to be routed to
   # and is used for super classing only
   #
-  # @api public
+  # :api: public
   def self.abstract!
     @_abstract = true
   end
@@ -364,7 +366,7 @@ class Merb::Controller < Merb::AbstractController
   # Boolean
   #  true if the controller has been set as abstract
   #
-  # @api public
+  # :api: public
   def self.abstract?
     !!@_abstract 
   end
@@ -383,7 +385,7 @@ class Merb::Controller < Merb::AbstractController
   # type<~to_s> ::
   #   The extension to append to the template path conditionally
   #
-  # @api private
+  # :api: private
   def _conditionally_append_extension(template, type)
     type && !template.match(/\.#{type.to_s.escape_regexp}$/) ? "#{template}.#{type}" : template
   end

data/lib/merb-core/controller/mime.rb

@@ -17,7 +17,7 @@ module Merb
     #   :default_quality   # the scale factor used in describing content type preference
     #   :response_block    # the block to be called with the controller when a request responds to this mime type
     #
-    # @api public
+    # :api: public
     def available_mime_types
       ResponderMixin::TYPES
     end
@@ -26,7 +26,7 @@ module Merb
     # Hash{String => Symbol}:: 
     #   A hash mapping Content-Type values to the mime type key of the appropriate entry in #available_mime_types
     #
-    # @api public
+    # :api: public
     def available_accepts
       ResponderMixin::MIMES
     end
@@ -66,7 +66,7 @@ module Merb
     # ==== Returns
     # nil
     #
-    # @api public
+    # :api: public
     def add_mime_type(key, transform_method, mimes, new_response_headers = {}, default_quality = 1, &block) 
       enforce!(key => Symbol, mimes => Array)
       
@@ -110,7 +110,7 @@ module Merb
     # ==== Notes
     # :all is the key for */*; It can't be removed.
     #
-    # @api public
+    # :api: public
     def remove_mime_type(key)
       return false if key == :all
       ResponderMixin::TYPES.delete(key)
@@ -125,7 +125,7 @@ module Merb
     # ==== Raises
     # ArgumentError:: The requested mime type is not valid.
     #
-    # @api private
+    # :api: private
     def mime_transform_method(key)
       raise ArgumentError, ":#{key} is not a valid MIME-type" unless ResponderMixin::TYPES.key?(key)
       ResponderMixin::TYPES[key][:transform_method]

data/lib/merb-core/controller/mixins/authentication.rb

@@ -75,7 +75,7 @@ module Merb::AuthenticationMixin
   #    end 
   #
   #
-  # @api public
+  # :api: public
   def basic_authentication(realm = "Application", &authenticator)
     @_basic_authentication ||= BasicAuthentication.new(self, realm, &authenticator)
   end
@@ -84,7 +84,7 @@ module Merb::AuthenticationMixin
     # So we can have access to the status codes
     include Merb::ControllerExceptions
 
-    # @api private
+    # :api: private
     def initialize(controller, realm = "Application", &authenticator)
       @controller = controller
       @realm = realm
@@ -101,6 +101,9 @@ module Merb::AuthenticationMixin
     #
     # ==== Returns
     # Object:: False if basic auth is not provided, otherwise the return value of the authenticator block.
+    # 
+    # @overridable
+    # :api: public
     def authenticate(&authenticator)
       if @auth.provided? and @auth.basic?
         authenticator.call(*@auth.credentials)
@@ -114,7 +117,7 @@ module Merb::AuthenticationMixin
     # ==== Throws
     # :halt with an "HTTP Basic: Access denied." message with no layout, and sets the status to Unauthorized.
     #
-    # @api public
+    # :api: public
     def request
       request!
       throw :halt, @controller.render("HTTP Basic: Access denied.\n", :status => Unauthorized.status, :layout => false)
@@ -125,7 +128,7 @@ module Merb::AuthenticationMixin
     # ==== Returns
     # String:: Returns the empty string to provide a response body.
     #
-    # @api public
+    # :api: public
     def request!
       @controller.status = Unauthorized.status
       @controller.headers['WWW-Authenticate'] = 'Basic realm="%s"' % @realm
@@ -135,7 +138,7 @@ module Merb::AuthenticationMixin
     # ==== Returns
     # Boolean:: Whether there has been any basic authentication credentials provided
     #
-    # @api public
+    # :api: public
     def provided?
       @auth.provided?
     end
@@ -143,7 +146,7 @@ module Merb::AuthenticationMixin
     # ==== Returns
     # String:: The username provided in the request.
     #
-    # @api public
+    # :api: public
     def username
       provided? ? @auth.credentials.first : nil
     end
@@ -151,14 +154,14 @@ module Merb::AuthenticationMixin
     # ==== Returns
     # String:: The password provided in the request.
     #
-    # @api public
+    # :api: public
     def password
       provided? ? @auth.credentials.last : nil
     end
     
     protected
     
-    # @api private
+    # :api: private
     def authenticate_or_request(&authenticator)
       authenticate(&authenticator) || request
     end

data/lib/merb-core/controller/mixins/conditional_get.rb

@@ -30,7 +30,7 @@ module Merb::ConditionalGetMixin
   #   value of ETag header enclosed in double quotes
   #   as required by the RFC
   #
-  # @api public
+  # :api: public
   def etag=(tag)
     headers[Merb::Const::ETAG] = %("#{tag}")
   end
@@ -39,7 +39,7 @@ module Merb::ConditionalGetMixin
   # <String>::
   #   Value of ETag response header or nil if it's not set.
   #
-  # @api public
+  # :api: public
   def etag
     headers[Merb::Const::ETAG]
   end
@@ -49,7 +49,7 @@ module Merb::ConditionalGetMixin
   # true if ETag response header equals If-None-Match request header,
   # false otherwise
   #
-  # @api public
+  # :api: public
   def etag_matches?(tag = self.etag)
     tag == self.request.if_none_match
   end
@@ -61,7 +61,7 @@ module Merb::ConditionalGetMixin
   # resource modification timestamp converted into format
   # required by the RFC
   #
-  # @api public
+  # :api: public
   def last_modified=(time)
     headers[Merb::Const::LAST_MODIFIED] = time.httpdate
   end
@@ -70,7 +70,7 @@ module Merb::ConditionalGetMixin
   # <String>::
   #   Value of Last-Modified response header or nil if it's not set.
   #
-  # @api public
+  # :api: public
   def last_modified
     Time.rfc2822(headers[Merb::Const::LAST_MODIFIED])
   end
@@ -80,7 +80,7 @@ module Merb::ConditionalGetMixin
   # true if Last-Modified response header is < than
   # If-Modified-Since request header value, false otherwise.
   #
-  # @api public
+  # :api: public
   def not_modified?(time = self.last_modified)
     request.if_modified_since && time && time <= request.if_modified_since
   end
@@ -90,7 +90,7 @@ module Merb::ConditionalGetMixin
   # true if either ETag matches or entity is not modified,
   # so request is fresh; false otherwise
   #
-  # @api public
+  # :api: public
   def request_fresh?
     etag_matches?(self.etag) || not_modified?(self.last_modified)
   end

data/lib/merb-core/controller/mixins/controller.rb

@@ -13,7 +13,7 @@ module Merb
     #   SomeBackgroundTask.run
     # end
     # 
-    # @api public
+    # :api: public
     def run_later(&blk)
       Merb::Dispatcher.work_queue << blk
     end
@@ -46,7 +46,7 @@ module Merb
     #     end
     #   end
     # 
-    # @api public
+    # :api: public
     def render_chunked(&blk)
       must_support_streaming!
       headers['Transfer-Encoding'] = 'chunked'
@@ -65,7 +65,7 @@ module Merb
     # ==== Parameters
     # data<String>:: a chunk of data to return.
     # 
-    # @api public
+    # :api: public
     def send_chunk(data)
       only_runs_on_mongrel!
       @response.write('%x' % data.size + "\r\n")
@@ -82,7 +82,7 @@ module Merb
     #   A block that the server can call later, allowing Merb to release the
     #   thread lock and render another request.
     # 
-    # @api public
+    # :api: public
     def render_deferred(&blk)
       Proc.new do |response|
         response.write(blk.call)
@@ -100,7 +100,7 @@ module Merb
     # Proc::
     #   A block that Mongrel can call after returning the string to the user.
     # 
-    # @api public
+    # :api: public
     def render_then_call(str, &blk)
       Proc.new do |response|
         response.write(str)
@@ -128,7 +128,7 @@ module Merb
     #   redirect("http://www.merbivore.com/")
     #   redirect("http://www.merbivore.com/", :permanent => true)
     # 
-    # @api public
+    # :api: public
     def redirect(url, opts = {})
       default_redirect_options = { :message => nil, :permanent => false }
       opts = default_redirect_options.merge(opts)
@@ -144,7 +144,7 @@ module Merb
     
     # Retreives the redirect message either locally or from the request.
     # 
-    # @api public
+    # :api: public
     def message
       @_message = defined?(@_message) ? @_message : request.message
     end
@@ -166,7 +166,7 @@ module Merb
     # ==== Returns
     # IO:: An I/O stream for the file.
     # 
-    # @api public
+    # :api: public
     def send_file(file, opts={})
       opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
       disposition = opts[:disposition].dup || 'attachment'
@@ -199,7 +199,7 @@ module Merb
     #   The name to use for the file. Defaults to the filename of file.
     # :type<String>:: The content type.
     # 
-    # @api public
+    # :api: public
     def send_data(data, opts={})
       opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
       disposition = opts[:disposition].dup || 'attachment'
@@ -235,7 +235,7 @@ module Merb
     #     end
     #   end
     # 
-    # @api public
+    # :api: public
     def stream_file(opts={}, &stream)
       opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
       disposition = opts[:disposition].dup || 'attachment'
@@ -277,7 +277,7 @@ module Merb
     # ==== Return
     # String:: precisely a single space.
     # 
-    # @api public
+    # :api: public
     def nginx_send_file(path, content_type = "")
       # Let Nginx detect content type unless it is explicitly set
       headers['Content-Type']        = content_type
@@ -297,7 +297,7 @@ module Merb
     # value<~to_s>:: A value for the cookie.
     # expires<~gmtime:~strftime, Hash>:: An expiration time for the cookie, or a hash of cookie options.
     # 
-    # @api public
+    # :api: public
     def set_cookie(name, value, expires)
       options = expires.is_a?(Hash) ? expires : {:expires => expires}
       cookies.set_cookie(name, value, options)
@@ -311,7 +311,7 @@ module Merb
     # ==== Parameters
     # name<~to_s>:: A name for the cookie to delete.
     # 
-    # @api public
+    # :api: public
     def delete_cookie(name)
       set_cookie(name, nil, Merb::Const::COOKIE_EXPIRED_TIME)
     end
@@ -324,7 +324,7 @@ module Merb
     # ==== Returns
     # String:: The escaped object.
     # 
-    # @api public
+    # :api: public
     def escape_xml(obj)
       Erubis::XmlHelper.escape_xml(obj.to_s)
     end
@@ -338,7 +338,7 @@ module Merb
     # ==== Raises
     # NotImplemented:: The Rack adapter is not mongrel.
     # 
-    # @api private
+    # :api: private
     def only_runs_on_mongrel!
       unless Merb::Config[:log_stream] == 'mongrel'
         raise(Merb::ControllerExceptions::NotImplemented, "Current Rack adapter is not mongrel. cannot support this feature")