merb-core 0.9.8 → 0.9.9

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

@@ -4,6 +4,8 @@ module Merb::RenderMixin
 
   # ==== Parameters
   # base<Module>:: Module that is including RenderMixin (probably a controller)
+  #
+  # @private
   def self.included(base)
     base.extend(ClassMethods)
     base.class_eval do
@@ -17,6 +19,8 @@ module Merb::RenderMixin
     #
     # ==== Returns
     # Hash:: An options hash
+    #
+    # @api public
     def default_render_options
       self._default_render_options ||= {}
     end
@@ -25,6 +29,8 @@ module Merb::RenderMixin
     #
     # ==== Parameters
     # opts<Hash>:: An options hash
+    #
+    # @api public
     def render_options(opts)
       self._default_render_options = opts
     end
@@ -40,11 +46,18 @@ module Merb::RenderMixin
     #
     # ==== Returns
     # Hash:: The default render options.
+    #
+    # @api public
     def layout(layout)
       self.default_render_options.update(:layout => (layout || false))
     end
 
     # Enable the default layout logic - reset the layout option.
+    #
+    # ==== Returns
+    # ~to_s:: The layout that was previously set.
+    #
+    # @api public
     def default_layout
       self.default_render_options.delete(:layout)
     end
@@ -82,8 +95,8 @@ module Merb::RenderMixin
   # ==== Alternatives
   # If you pass a Hash as the first parameter, it will be moved to opts and
   # "thing" will be the current action
-  #---
-  # @public
+  #
+  # @api public
   def render(thing = nil, opts = {})
     # render :format => :xml means render nil, :format => :xml
     opts, thing = thing, nil if thing.is_a?(Hash)
@@ -188,6 +201,7 @@ module Merb::RenderMixin
   # The transformed object will not be used in a layout unless a :layout is
   # explicitly passed in the opts.
   #
+  # @api public
   def display(object, thing = nil, opts = {})
     template_opt = thing.is_a?(Hash) ? thing.delete(:template) : opts.delete(:template)
 
@@ -268,6 +282,8 @@ module Merb::RenderMixin
   #
   # In this case, "one" will be available in the partial through the local
   # variable named +number+.
+  #
+  # @api public
   def partial(template, opts={})
 
     # partial :foo becomes "#{controller_name}/_foo"
@@ -323,6 +339,8 @@ module Merb::RenderMixin
   #
   # ==== Returns
   # Hash:: The options hash that was passed in.
+  #
+  # @api private
   def _handle_options!(opts)
     self.status = opts.delete(:status).to_i if opts[:status]
     headers["Location"] = opts.delete(:location) if opts[:location]
@@ -346,6 +364,8 @@ module Merb::RenderMixin
   #   If a layout was specified (either via layout in the class or by passing
   #   one in to this method), and not found. No error will be raised if no
   #   layout was specified, and the default layouts were not found.
+  #
+  # @api private
   def _get_layout(layout = nil)
     return false if layout == false
     
@@ -385,6 +405,8 @@ module Merb::RenderMixin
   # ==== Returns
   # Array[Symbol, String]::
   #   A pair consisting of the template method and location.
+  #
+  # @api private
   def _template_for(context, content_type, controller=nil, template=nil, locals=[])
     template_method, template_location = nil, nil
 
@@ -419,6 +441,8 @@ module Merb::RenderMixin
   #
   # ==== Returns
   # String:: The method, if it exists. Otherwise return nil.
+  #
+  # @api private
   def _template_method_for(template_location, locals)
     meth = Merb::Template.template_for(template_location, [], locals)
     meth && self.respond_to?(meth) ? meth : nil
@@ -431,8 +455,8 @@ module Merb::RenderMixin
   #
   # ==== Parameters
   # obj<Object>:: The key in the thrown_content hash. Defaults to :for_layout.
-  #---
-  # @public
+  #
+  # @api public
   def catch_content(obj = :for_layout)
     @_caught_content[obj] || ''
   end
@@ -441,8 +465,8 @@ module Merb::RenderMixin
   #
   # ==== Parameters
   # obj<Object>:: The key in the thrown_content hash. Defaults to :for_layout.
-  #---
-  # @public
+  #
+  # @api public
   def thrown_content?(obj = :for_layout)
     @_caught_content.key?(obj)
   end
@@ -463,8 +487,8 @@ module Merb::RenderMixin
   # ==== Example
   #   throw_content(:foo, "Foo")
   #   catch_content(:foo) #=> "Foo"
-  #---
-  # @public
+  #
+  # @api public
   def throw_content(obj, string = nil, &block)
     unless string || block_given?
       raise ArgumentError, "You must pass a block or a string into throw_content"
@@ -499,8 +523,8 @@ module Merb::RenderMixin
   #
   # ==== Parameters
   # obj<Object>:: The key in the thrown_content hash. Defaults to :for_layout.
-  #---
-  # @public
+  #
+  # @api public
   def clear_content(obj = :for_layout)
     @_caught_content.delete(obj) unless @_caught_content[obj].nil?
   end

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

@@ -104,6 +104,8 @@ module Merb
     
     # ==== Parameters
     # base<Module>:: The module that ResponderMixin was mixed into
+    #
+    # @api private
     def self.included(base)
       base.extend(ClassMethods)
       base.class_eval do
@@ -130,8 +132,8 @@ module Merb
       #
       # ==== Examples
       #   provides :html, :xml
-      #---
-      # @public
+      #
+      # @api public
       def provides(*formats)
         self.class_provided_formats |= formats
       end
@@ -145,8 +147,7 @@ module Merb
       # ==== Returns
       # Array[Symbol]:: List of formats passed in.      
       #
-      #---
-      # @public
+      # @api public
       def only_provides(*formats)
         clear_provides
         provides(*formats)
@@ -162,8 +163,7 @@ module Merb
       # Array[Symbol]::
       #   List of formats that remain after removing the ones not to provide.
       #
-      #---
-      # @public
+      # @api public
       def does_not_provide(*formats)
         self.class_provided_formats -= formats
       end
@@ -172,6 +172,8 @@ module Merb
       #
       # ==== Returns
       # Array:: An empty Array.
+      #
+      # @api public
       def clear_provides
         self.class_provided_formats.clear
       end
@@ -180,6 +182,8 @@ module Merb
       #
       # ==== Returns
       # Array[Symbol]:: [:html].
+      #
+      # @api public
       def reset_provides
         only_provides(:html)
       end
@@ -190,6 +194,8 @@ module Merb
     #   The current list of formats provided for this instance of the
     #   controller. It starts with what has been set in the controller (or
     #   :html by default) but can be modifed on a per-action basis.      
+    #
+    # @api private
     def _provided_formats
       @_provided_formats ||= class_provided_formats.dup
     end
@@ -209,8 +215,7 @@ module Merb
     # ==== Returns
     # Array[Symbol]:: List of formats passed in.
     #
-    #---
-    # @public
+    # @api public
     def provides(*formats)
       if @_content_type
         raise ContentTypeAlreadySet, "Cannot modify provided_formats because content_type has already been set"
@@ -229,8 +234,7 @@ module Merb
     # ==== Returns
     # Array[Symbol]:: List of formats passed in.
     #
-    #---
-    # @public
+    # @api public
     def only_provides(*formats)
       @_provided_formats = []
       provides(*formats)
@@ -248,8 +252,7 @@ module Merb
     # Array[Symbol]::
     #   List of formats that remain after removing the ones not to provide.
     #
-    #---
-    # @public
+    # @api public
     def does_not_provide(*formats)
       @_provided_formats -= formats.flatten
     end
@@ -260,6 +263,8 @@ module Merb
     # 3. If it's */*, use the first provided format
     # 4. Look for one that is provided, in order of request
     # 5. Raise 406 if none found
+    #
+    # @api private
     def _perform_content_negotiation
       if (fmt = params[:format]) && !fmt.empty?
         accepts = [fmt.to_sym]
@@ -307,8 +312,7 @@ module Merb
     # ==== Returns
     # Symbol:: The content-type that will be used for this controller.
     #
-    #---
-    # @public
+    # @api public
     def content_type(fmt = nil)
       self.content_type = (fmt || _perform_content_negotiation) unless @_content_type
       @_content_type
@@ -327,8 +331,7 @@ module Merb
     # ==== Returns
     # Symbol:: The content-type that was passed in.
     #
-    #---
-    # @semipublic
+    # @api plugin
     def content_type=(type)
       unless Merb.available_mime_types.has_key?(type)
         raise Merb::ControllerExceptions::NotAcceptable.new("Unknown content_type for response: #{type}") 
@@ -359,6 +362,8 @@ module Merb
     #
     # ==== Returns
     # Array[AcceptType]:: The accepted types.
+    #
+    # @private
     def self.parse(accept_header)
       headers = accept_header.split(/,/)
       idx, list = 0, []
@@ -378,6 +383,8 @@ module Merb
     # index<Fixnum>::
     #   The index used for sorting accept types. A lower value indicates higher
     #   priority.
+    # 
+    # @api private
     def initialize(entry,index)
       @index = index
       
@@ -399,6 +406,8 @@ module Merb
     # Fixnum::
     #   -1, 0 or 1, depending on whether entry has a lower, equal or higher
     #   priority than the accept type being compared.
+    #
+    # @api private
     def <=>(entry)
       if entry.quality == quality
         @index <=> entry.index
@@ -415,20 +424,28 @@ module Merb
     # Boolean::
     #   True if the accept types are equal, i.e. if the synonyms for this
     #   accept type includes the entry media range.
+    #
+    # @api private
     def eql?(entry)
       synonyms.include?(entry.media_range)
     end
 
     # An alias for eql?.
+    #
+    # @api private
     def ==(entry); eql?(entry); end
 
     # ==== Returns
     # Fixnum:: A hash based on the super range.
+    #
+    # @api private
     def hash; super_range.hash; end
 
     # ==== Returns
     # Array[String]::
     #   All Accept header values, such as "text/html", that match this type.
+    #
+    # @api private
     def synonyms
       return @syns if @syns
       if _mime = mime
@@ -438,6 +455,7 @@ module Merb
       end
     end
     
+    # @api private
     def mime
       @mime ||= Merb.available_mime_types[Merb::ResponderMixin::MIMES[@media_range]]
     end
@@ -446,12 +464,16 @@ module Merb
     # String::
     #   The primary media range for this accept type, i.e. either the first
     #   synonym or, if none exist, the media range.
+    #
+    # @api private
     def super_range
       synonyms.first || @media_range
     end
 
     # ==== Returns
     # Symbol: The type as a symbol, e.g. :html.
+    #
+    # @api private
     def to_sym
       Merb.available_mime_types.select{|k,v| 
         v[:accepts] == synonyms || v[:accepts][0] == synonyms[0]}.flatten.first
@@ -459,6 +481,8 @@ module Merb
 
     # ==== Returns
     # String:: The accept type as a string, i.e. the media range.
+    #
+    # @api private
     def to_s
       @media_range
     end

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

@@ -21,10 +21,12 @@ module Merb::Template
     # ==== Returns
     # String:: The template name.
     #
-    #---
+    #
     # We might want to replace this with something that varies the
     # character replaced based on the non-alphanumeric character
     # to avoid edge-case collisions.
+    #
+    # @api private
     def template_name(path)
       path = File.expand_path(path)      
       path.gsub(/[^\.a-zA-Z0-9]/, "__").gsub(/\./, "_")
@@ -45,8 +47,9 @@ module Merb::Template
     # 
     # ==== Returns
     # IO#path:: An IO object that responds to path (File or VirtualFile).
-    #---
-    # @semipublic
+    #
+    # @api plugin
+    # @overridable
     def load_template_io(path)
       File.open(path, "r")
     end
@@ -60,8 +63,8 @@ module Merb::Template
     #
     # ==== Returns
     # <String>:: name of the method that inlines the template.
-    #---
-    # @semipublic
+    #
+    # @api private
     def template_for(path, template_stack = [], locals=[])
       path = File.expand_path(path)
       
@@ -81,20 +84,22 @@ module Merb::Template
     #
     # ==== Returns
     # Boolean:: Whether or not the template for the provided path needs to be recompiled
-    #---
+    #
+    # @api private
     def needs_compilation?(path, locals)
       return true if Merb::Config[:reload_templates] || !METHOD_LIST[path]
       
       current_locals = SUPPORTED_LOCALS_LIST[path]
-      locals.any?{|local| !current_locals.include?(local)}
+      current_locals != locals &&
+        !(locals - current_locals).empty?
     end
     
     # Get all known template extensions
     #
     # ==== Returns
     #   Array:: Extension strings.
-    #---
-    # @semipublic
+    #
+    # @api plugin
     def template_extensions
       EXTENSIONS.keys
     end
@@ -112,11 +117,14 @@ module Merb::Template
     #   The module to put the compiled method into. Defaults to
     #   Merb::InlineTemplates
     #
+    # ==== Returns
+    # Symbol:: The name of the method that the template was compiled into.
+    #
     # ==== Notes
     # Even though this method supports inlining into any module, the method
     # must be available to instances of AbstractController that will use it.
-    #---
-    # @public
+    #
+    # @api private
     def inline_template(io, locals=[], mod = Merb::InlineTemplates)
       full_file_path = File.expand_path(io.path)
       engine_neutral_path = full_file_path.gsub(/\.[^\.]*$/, "")
@@ -136,8 +144,8 @@ module Merb::Template
     #
     # ==== Returns
     # Class:: The engine.
-    #---
-    # @semipublic
+    #
+    # @api private
     def engine_for(path)
       path = File.expand_path(path)      
       EXTENSIONS[path.match(/\.([^\.]*)$/)[1]]
@@ -155,10 +163,13 @@ module Merb::Template
     # ==== Raises
     # ArgumentError:: engine does not have a compile_template method.
     #
+    # ==== Returns
+    # nil
+    #
     # ==== Example
     #   Merb::Template.register_extensions(Merb::Template::Erubis, ["erb"])
-    #---
-    # @public
+    #
+    # @api plugin
     def register_extensions(engine, extensions) 
       raise ArgumentError, "The class you are registering does not have a compile_template method" unless
         engine.respond_to?(:compile_template)
@@ -177,6 +188,8 @@ module Merb::Template
     # name<String>:: The name of the method that will be created.
     # locals<Array[Symbol]>:: A list of locals to assign from the args passed into the compiled template.
     # mod<Module>:: The module that the compiled method will be placed into.
+    #
+    # @api private
     def self.compile_template(io, name, locals, mod)
       template = ::Erubis::BlockAwareEruby.new(io.read)
       _old_verbose, $VERBOSE = $VERBOSE, nil
@@ -206,6 +219,8 @@ module Merb::Template
       #   <% @foo = capture do %>
       #     <p>Some Foo content!</p> 
       #   <% end %>
+      #
+      # @private
       def capture_erb(*args, &block)
         _old_buf, @_erb_buf = @_erb_buf, ""
         block.call(*args)
@@ -214,7 +229,7 @@ module Merb::Template
         ret
       end
 
-      # DOC
+      # @private
       def concat_erb(string, binding)
         @_erb_buf << string
       end
@@ -228,30 +243,36 @@ end
 
 module Erubis
   module BlockAwareEnhancer
+    # @api private
     def add_preamble(src)
       src << "_old_buf, @_erb_buf = @_erb_buf, ''; "
       src << "@_engine = 'erb'; "
     end
 
+    # @api private
     def add_postamble(src)
       src << "\n" unless src[-1] == ?\n      
       src << "_ret = @_erb_buf; @_erb_buf = _old_buf; _ret.to_s;\n"
     end
 
+    # @api private
     def add_text(src, text)
       src << " @_erb_buf.concat('" << escape_text(text) << "'); "
     end
 
+    # @api private
     def add_expr_escaped(src, code)
       src << ' @_erb_buf.concat(' << escaped_expr(code) << ');'
     end
     
+    # @api private
     def add_stmt2(src, code, tailch)
       src << code
       src << " ).to_s; " if tailch == "="
       src << ';' unless code[-1] == ?\n
     end
     
+    # @api private
     def add_expr_literal(src, code)
       if code =~ /(do|\{)(\s*\|[^|]*\|)?\s*\Z/
         src << ' @_erb_buf.concat( ' << code << "; "