Add API level to many methods

merb-core/lib/merb-core.rb

@@ -194,9 +194,14 @@ def restart_environment(argv={})
       start_environment(Merb::Config.to_hash.merge(argv))
     end
 
-    attr_accessor :environment, :load_paths, :adapter, :environment_info, :started
+    # @api public
+    attr_accessor :environment, :adapter
+    # @api private
+    attr_accessor :load_paths, :environment_info, :started
 
+    # @api public
     alias :env :environment
+    # @api public
     alias :started? :started
 
     Merb.load_paths = Dictionary.new { [Merb.root] } unless Merb.load_paths.is_a?(Dictionary)

merb-core/lib/merb-core/bootloader.rb

@@ -321,6 +321,8 @@ class << self
     #
     # ==== Returns
     # nil
+    #
+    # @api plugin
     def run
       $:.push Merb.root unless Merb.root == File.expand_path(Dir.pwd)
       build_framework
@@ -1042,6 +1044,8 @@ def run
     #
     # ==== Returns
     # String:: The path to the router file if it exists, nil otherwise.
+    #
+    # @api private
     def router_file
       @router_file ||= begin
         if File.file?(router = Merb.dir_for(:router) / Merb.glob_for(:router))

merb-core/lib/merb-core/config.rb

@@ -85,6 +85,8 @@ def [](key)
       # ==== Parameters
       # key<Object>:: The key to set the parameter for.
       # val<Object>:: The value of the parameter.
+      #
+      # @api public
       def []=(key, val)
         (@configuration ||= setup)[key] = val
       end
@@ -111,6 +113,8 @@ def delete(key)
       #
       # ==== Returns
       # Object:: The value of the configuration parameter or the default.
+      #
+      # @api public
       def fetch(key, default)
         @configuration.fetch(key, default)
       end
@@ -400,6 +404,7 @@ def parse_args(argv = ARGV)
         Merb::Config.setup(options)
       end
 
+      # @api private
       attr_accessor :configuration
 
       # Set configuration parameters from a code block, where each method

merb-core/lib/merb-core/controller/abstract_controller.rb

@@ -95,20 +95,20 @@
 class Merb::AbstractController
   include Merb::RenderMixin
   include Merb::InlineTemplates
-  
+
   class_inheritable_accessor :_layout, :_template_root, :template_roots
   class_inheritable_accessor :_before_filters, :_after_filters
   class_inheritable_accessor :_before_dispatch_callbacks, :_after_dispatch_callbacks
 
   cattr_accessor :_abstract_subclasses
 
-  #---
-  # @api semipublic
-  attr_accessor :body
-  attr_accessor :action_name
-  attr_accessor :_benchmarks, :_thrown_content  
+  # @api plugin
+  attr_accessor :body, :action_name, :_benchmarks
+  # @api private
+  attr_accessor :_thrown_content  
 
   # Stub so content-type support in RenderMixin doesn't throw errors
+  # @api private
   attr_accessor :content_type
 
   FILTER_OPTIONS = [:only, :exclude, :if, :unless, :with]
@@ -205,7 +205,7 @@ def self._reset_template_roots
   #   Template roots as pairs of template root path and template location
   #   method.
   #
-  # @api unknown
+  # @api plugin
   def self._template_roots
     self.template_roots || _reset_template_roots
   end
@@ -215,7 +215,7 @@ def self._template_roots
   #   Template roots as pairs of template root path and template location
   #   method.
   #
-  # @api unknown
+  # @api plugin
   def self._template_roots=(roots)
     self.template_roots = roots
   end
@@ -248,7 +248,7 @@ def self.inherited(klass)
   # ==== Parameters
   # *args:: The args are ignored in this class, but we need this so that subclassed initializes can have parameters
   #
-  # @overridable
+  # @api private
   def initialize(*args)
     @_benchmarks = {}
     @_caught_content = {}

merb-core/lib/merb-core/controller/exceptions.rb

@@ -154,6 +154,9 @@ class Base < StandardError #:doc:
 
       # === Returns
       # Integer:: The status-code of the error.
+      # 
+      # @overridable
+      # @api plugin
       def status; self.class.status; end
       alias :to_i :status
 
@@ -338,6 +341,8 @@ class HTTPVersionNotSupported     < Merb::ControllerExceptions::ServerError; sel
   # Required to show exceptions in the log file
   #
   # e<Exception>:: The exception that a message is being generated for
+  #
+  # @api plugin
   def self.exception(e)
     "#{ e.message } - (#{ e.class })\n" <<  
     "#{(e.backtrace or []).join("\n")}" 

merb-core/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
@@ -195,6 +196,7 @@ def _dispatch(action=:index)
     self
   end
 
+  # @api public
   attr_reader :request, :headers
 
   # ==== Returns

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

@@ -101,6 +101,9 @@ def initialize(controller, realm = "Application", &authenticator)
     #
     # ==== 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)

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

@@ -220,7 +220,7 @@ module Mixin
       #     <p>Some Foo content!</p> 
       #   <% end %>
       #
-      # @private
+      # @api private
       def capture_erb(*args, &block)
         _old_buf, @_erb_buf = @_erb_buf, ""
         block.call(*args)
@@ -229,7 +229,7 @@ def capture_erb(*args, &block)
         ret
       end
 
-      # @private
+      # @api private
       def concat_erb(string, binding)
         @_erb_buf << string
       end

merb-core/lib/merb-core/core_ext/kernel.rb

@@ -2,6 +2,7 @@
 
 module Gem
   class Dependency
+    # @api private
     attr_accessor :require_block, :require_as
   end
 end

merb-core/lib/merb-core/dispatch/cookies.rb

@@ -2,6 +2,7 @@ module Merb
 
   class Cookies < Mash
 
+    # @api private
     def initialize(constructor = {})
       @_options_lookup  = Mash.new
       @_cookie_defaults = { "domain" => Merb::Controller._default_cookie_domain, "path" => '/' }
@@ -17,6 +18,8 @@ def initialize(constructor = {})
     # ==== Notes
     # By using this method, a cookie key is marked for being
     # included in the Set-Cookie response header.
+    #
+    # @api public
     def []=(key, value)
       @_options_lookup[key] ||= {}
       super
@@ -38,6 +41,8 @@ def []=(key, value)
     # ==== Notes
     # By using this method, a cookie key is marked for being
     # included in the Set-Cookie response header.
+    #
+    # @api private
     def set_cookie(name, value, options = {})
       @_options_lookup[name] = options
       self[name] = value
@@ -49,6 +54,8 @@ def set_cookie(name, value, options = {})
     # ==== Parameters
     # name<~to_s>:: Name of the cookie to delete.
     # options<Hash>:: Additional options to pass to +set_cookie+.
+    #
+    # @api public
     def delete(name, options = {})
       set_cookie(name, "", options.merge("expires" => Time.at(0)))
     end
@@ -57,6 +64,8 @@ def delete(name, options = {})
     #
     # ==== Returns
     # Hash:: The headers to set, or an empty array if no cookies are set.
+    #
+    # @api private
     def extract_headers(controller_defaults = {})
       defaults = @_cookie_defaults.merge(controller_defaults)
       cookies = []
@@ -101,6 +110,8 @@ def self.included(base)
     # ==== Notes
     # Headers are passed into the cookie object so that you can do:
     #   cookies[:foo] = "bar"
+    #
+    # @api public
     def cookies
       request.cookies
     end
@@ -114,6 +125,8 @@ module RequestMixin
       # If a method #default_cookies is defined it will be called. This can
       # be used for session fixation purposes for example. The method returns
       # a Hash of key => value pairs.
+      #
+      # @api public
       def cookies
         @cookies ||= begin
           values  = Merb::Parse.query(@env[Merb::Const::HTTP_COOKIE], ';,')

merb-core/lib/merb-core/dispatch/default_exception/default_exception.rb

@@ -1,10 +1,14 @@
 module Merb
   class Dispatcher
+    # @api private
     module DefaultExceptionHelper
+
+      # @api private
       def humanize_exception(e)
         e.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1 \2')
       end
 
+      # @api private
       def error_codes(exception)
         if @show_details
           message, message_details = exception.message.split("\n", 2)
@@ -14,6 +18,7 @@ def error_codes(exception)
         end
       end
 
+      # @api private
       def frame_details(line)
         filename, lineno, location = line.split(":")
         if filename.index(Merb.framework_root)
@@ -32,6 +37,7 @@ def frame_details(line)
         [type, shortname, filename, lineno, location]
       end
 
+      # @api private
       def listing(key, value, arr)
         ret   =  []
         ret   << "<table class=\"listing\" style=\"display: none\">"
@@ -51,10 +57,12 @@ def listing(key, value, arr)
         ret.join("\n")
       end
 
+      # @api private
       def textmate_url(filename, line)
         "<a href='txmt://open?url=file://#{filename}&amp;line=#{line}'>#{line}</a>"
       end
 
+      # @api private
       def render_source(filename, line)
         line = line.to_i
         ret   =  []
@@ -76,13 +84,16 @@ def render_source(filename, line)
       end
     end
 
+    # @api private
     class DefaultException < Merb::Controller
       self._template_root = File.dirname(__FILE__) / "views"
 
+      # @api private
       def _template_location(context, type = nil, controller = controller_name)
         "#{context}.#{type}"
-      end    
+      end
 
+      # @api private
       def index
         @exceptions = request.exceptions
         @show_details = Merb::Config[:exception_details]

merb-core/lib/merb-core/dispatch/dispatcher.rb

@@ -5,6 +5,7 @@ class Dispatcher
     class << self
       include Merb::ControllerExceptions
 
+      # @api private
       attr_accessor :use_mutex
 
       @@work_queue = Queue.new

merb-core/lib/merb-core/dispatch/request.rb

@@ -3,8 +3,12 @@
 module Merb
 
   class Request
-    # def env def exceptions def route_params
-    attr_accessor :env, :exceptions, :route
+
+    # @api private
+    attr_accessor :env, :route
+    # @api public
+    attr_accessor :exceptions
+    # @api private
     attr_reader :route_params
 
     # by setting these to false, auto-parsing is disabled; this way you can

merb-core/lib/merb-core/dispatch/router/cached_proc.rb

@@ -2,20 +2,26 @@ module Merb
 
   class Router
     # Cache procs for future reference in eval statement
+    # @api private
     class CachedProc
       @@index = 0
       @@list = []
 
+      # @api private
       attr_accessor :cache, :index
 
       # ==== Parameters
       # cache<Proc>:: The block of code to cache.
+      #
+      # @api private
       def initialize(cache)
         @cache, @index = cache, CachedProc.register(self)
       end
 
       # ==== Returns
       # String:: The CachedProc object in a format embeddable within a string.
+      #
+      # @api private
       def to_s
         "CachedProc[#{@index}].cache"
       end
@@ -27,6 +33,8 @@ class << self
         #
         # ==== Returns
         # Fixnum:: The index of the newly registered CachedProc.
+        #
+        # @api private
         def register(cached_code)
           CachedProc[@@index] = cached_code
           @@index += 1
@@ -38,13 +46,17 @@ def register(cached_code)
         # ==== Parameters
         # index<Fixnum>:: The index of the cached code to set.
         # code<CachedProc>:: The cached code to set.
+        #
+        # @api private
         def []=(index, code) @@list[index] = code end
 
         # ==== Parameters
         # index<Fixnum>:: The index of the cached code to retrieve.
         #
         # ==== Returns
         # CachedProc:: The cached code at index.
+        #
+        # @api private
         def [](index) @@list[index] end
       end
     end # CachedProc