yard 0.6.3 → 0.6.4

data/lib/yard/server/commands/display_object_command.rb

@@ -1,6 +1,7 @@
 module YARD
   module Server
     module Commands
+      # Displays documentation for a specific object identiied by the path
       class DisplayObjectCommand < LibraryCommand
         def run
           return index if path.empty?

data/lib/yard/server/commands/frames_command.rb

@@ -1,6 +1,7 @@
 module YARD
   module Server
     module Commands
+      # Displays an object wrapped in frames
       class FramesCommand < DisplayObjectCommand
         include DocServerHelper
         

data/lib/yard/server/commands/library_command.rb

@@ -1,6 +1,12 @@
 module YARD
   module Server
     module Commands
+      # This is the base command for all commands that deal directly with libraries.
+      # Some commands do not, but most (like {DisplayObjectCommand}) do. If your
+      # command deals with libraries directly, subclass this class instead.
+      # See {Base} for notes on how to subclass a command.
+      # 
+      # @abstract
       class LibraryCommand < Base
         # @return [LibraryVersion] the object containing library information
         attr_accessor :library
@@ -42,7 +48,7 @@ module YARD
         rescue LibraryNotPreparedError
           not_prepared
         end
-
+        
         private
 
         def setup_library
@@ -85,6 +91,7 @@ module YARD
           [302, {'Content-Type' => 'text/html'}, [render]]
         end
         
+        # @private
         @@last_yardoc = nil
       end
     end

data/lib/yard/server/commands/list_command.rb

@@ -1,6 +1,7 @@
 module YARD
   module Server
     module Commands
+      # Returns a list of objects of a specific type
       class ListCommand < LibraryCommand
         include Templates::Helpers::BaseHelper
         
@@ -14,6 +15,7 @@ module YARD
         end
       end
       
+      # Returns the list of classes / modules in a library
       class ListClassesCommand < ListCommand
         def type; :class end
         
@@ -23,6 +25,7 @@ module YARD
         end
       end
       
+      # Returns the list of methods in a library
       class ListMethodsCommand < ListCommand
         include Templates::Helpers::ModuleHelper
         
@@ -35,6 +38,7 @@ module YARD
         end
       end
       
+      # Returns the list of README/extra files in a library
       class ListFilesCommand < ListCommand
         def type; :files end
         def items; options[:files] end

data/lib/yard/server/doc_server_helper.rb

@@ -1,21 +1,36 @@
 module YARD
   module Server
+    # A module that is mixed into {Templates::Template} in order to customize
+    # certain template methods.
     module DocServerHelper
+      # Modifies {Templates::Helpers::HtmlHelper#url_for} to return a URL instead
+      # of a disk location.
+      # @param (see Templates::Helpers::HtmlHelper#url_for)
+      # @return (see Templates::Helpers::HtmlHelper#url_for)
       def url_for(obj, anchor = nil, relative = false)
         return '' if obj.nil?
         return "/#{obj}" if String === obj
         super(obj, anchor, false)
       end
 
+      # Modifies {Templates::Helpers::HtmlHelper#url_for_file} to return a URL instead
+      # of a disk location.
+      # @param (see Templates::Helpers::HtmlHelper#url_for_file)
+      # @return (see Templates::Helpers::HtmlHelper#url_for_file)
       def url_for_file(filename, anchor = nil)
         "/#{base_path(router.docs_prefix)}/file/" + filename.sub(%r{^#{@library.source_path.to_s}/}, '') + 
           (anchor ? "##{anchor}" : "")
       end
       
+      # @example The base path for a library 'foo'
+      #   base_path('docs') # => 'docs/foo'
+      # @param [String] path the path prefix for a base path URI
+      # @return [String] the base URI for a library with an extra +path+ prefix
       def base_path(path)
         path + (@single_library ? '' : "/#{@library}")
       end
       
+      # @return [Router] convenience method for accessing the router
       def router; @adapter.router end
     end
   end

data/lib/yard/server/doc_server_serializer.rb

@@ -2,6 +2,8 @@ require 'webrick/httputils'
 
 module YARD
   module Server
+    # A custom {Serializers::Base serializer} which returns resource URLs instead of
+    # static relative paths to files on disk.
     class DocServerSerializer < Serializers::FileSystemSerializer
       include WEBrick::HTTPUtils
       

data/lib/yard/server/library_version.rb

@@ -2,15 +2,121 @@ require 'fileutils'
 
 module YARD
   module Server
+    # This exception is raised when {LibraryVersion#prepare!} fails, or discovers
+    # that the library is not "prepared" to be served by 
     class LibraryNotPreparedError < RuntimeError; end
     
+    # A library version encapsulates a library's documentation at a specific version.
+    # Although the version is optional, this allows for creating multiple documentation
+    # points for a specific library, each representing a unique version. The term
+    # "library" used in other parts of the YARD::Server documentation refers to 
+    # objects of this class unless otherwise noted.
+    # 
+    # A library points to a location where a {#yardoc_file} is located so that
+    # its documentation may be loaded and served. Optionally, a {#source_path} is
+    # given to point to a location where any extra files (and {YARD::CLI::Yardoc .yardopts}) 
+    # should be loaded from. Both of these methods may not be known immediately, 
+    # since the yardoc file may not be built until later. Resolving the yardoc 
+    # file and source path are dependent on the specific library "source type" used.
+    # Source types (known as "library source") are discussed in detail below.
+    # 
+    # == Using with Adapters
+    # A list of libraries need to be passed into adapters upon creation. In
+    # most cases, you will never do this manually, but if you use a {RackMiddleware},
+    # you will need to pass in this list yourself. To build this list of libraries,
+    # you should create a hash of library names mapped to an *Array* of LibraryVersion
+    # objects. For example:
+    # 
+    #   {'mylib' => [LibraryVersion.new('mylib', '1.0', ...), 
+    #                LibraryVersion.new('mylib', '2.0', ...)]}
+    # 
+    # Note that you can also use {Adapter#add_library} for convenience.
+    # 
+    # The "array" part is required, even for just one library version.
+    # 
+    # == Library Sources
+    # The {#source} method represents the library source type, ie. where the
+    # library "comes from". It might come from "disk", or it might come from a
+    # "gem" (technically the disk, but a separate type nonetheless). In these
+    # two cases, the yardoc file sits somewhere on your filesystem, though
+    # it may also be built dynamically if it does not yet exist. This behaviour
+    # is controlled through the {#prepare!} method, which prepares the yardoc file
+    # given a specific library source. We will see how this works in detail in
+    # the following section.
+    # 
+    # == Implementing a Custom Library Source
+    # YARD can be extended to support custom library sources in order to 
+    # build or retrieve a yardoc file at runtime from many different locations.
+    # 
+    # To implement this behaviour, two methods must be added to the +LibraryVersion+
+    # class, +#load_yardoc_from_SOURCE+ and +#source_path_for_SOURCE+. In both
+    # cases, "SOURCE" represents the source type used in {#source} when creating
+    # the library object. The +#source_path_for_SOURCE+ method is called upon
+    # creation and should return the location where the source code for the library 
+    # lives. The load method is called from {#prepare!} if there is no yardoc file
+    # and should set {#yardoc_file}. Below is a full example for
+    # implementing a custom library source, +:http+, which reads packaged .yardoc
+    # databases from zipped archives off of an HTTP server.
+    # 
+    # @example Implementing a Custom Library Source
+    #   # Adds the source type "http" for .yardoc files zipped on HTTP servers
+    #   class LibraryVersion
+    #     def load_yardoc_from_http
+    #       return if yardoc_file # we have the library
+    # 
+    #       # otherwise download it in a thread and return immediately
+    #       Thread.new do 
+    #         # zip/unzip method implementations are not shown
+    #         download_zip_file("http://mysite.com/yardocs/#{self}.zip")
+    #         unzip_file_to("/path/to/yardocs/#{self}")
+    #         self.yardoc_file = "/path/to/yardocs/#{self}/.yardoc"
+    #         self.source_path = self.yardoc_file
+    #       end
+    # 
+    #       # tell the server it's not ready yet (but it might be next time)
+    #       raise LibraryNotPreparedError
+    #     end
+    # 
+    #     # we set this later
+    #     def source_path_for_http; nil end
+    #   end
+    # 
+    #   # Creating a library of this source type:
+    #   LibraryVersion.new('name', '1.0', nil, :http)
+    # 
     class LibraryVersion
+      # @return [String] the name of the library
       attr_accessor :name
+      
+      # @return [String] the version of the specific library
       attr_accessor :version
+      
+      # @return [String] the location of the yardoc file used to load the object
+      #   information from.
+      # @return [nil] if no yardoc file exists yet. In this case, {#prepare!} will
+      #   be called on this library to build the yardoc file.
       attr_accessor :yardoc_file
+      
+      # @return [Symbol] the source type representing where the yardoc should be
+      #   loaded from. Defaults are +:disk+ and +:gem+, though custom sources
+      #   may be implemented. This value is used to inform {#prepare!} about how
+      #   to load the necessary data in order to display documentation for an object.
+      # @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
       attr_accessor :source
+      
+      # @return [String] the location of the source code for a library. This
+      #   value is filled by calling +#source_path_for_SOURCE+ on this class.
+      # @return [nil] if there is no source code
+      # @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
       attr_accessor :source_path
       
+      # @param [String] name the name of the library
+      # @param [String] version the specific (usually, but not always, numeric) library
+      #   version
+      # @param [String] yardoc the location of the yardoc file, or nil if it is
+      #   generated later
+      # @param [Symbol] source the location of the files used to build the yardoc.
+      #   Builtin source types are +:disk+ or +:gem+.
       def initialize(name, version = nil, yardoc = nil, source = :disk)
         self.name = name
         self.yardoc_file = yardoc
@@ -19,12 +125,18 @@ module YARD
         self.source_path = load_source_path
       end
       
+      # @param [Boolean] url_format if true, returns the string in a URI-compatible
+      #   format (for appending to a URL). Otherwise, it is given in a more human
+      #   readable format.
+      # @return [String] the string representation of the library.
       def to_s(url_format = true)
         version ? "#{name}#{url_format ? '/' : '-'}#{version}" : "#{name}"
       end
       
+      # @return [Fixnum] used for Hash mapping.
       def hash; to_s.hash end
       
+      # @return [Boolean] whether another LibraryVersion is equal to this one
       def eql?(other)
         other.is_a?(LibraryVersion) && other.name == name && 
           other.version == version && other.yardoc_file == yardoc_file
@@ -32,12 +144,30 @@ module YARD
       alias == eql?
       alias equal? eql?
       
+      # @note You should not directly override this method. Instead, implement
+      #   +load_yardoc_from_SOURCENAME+ when implementing loading for a specific
+      #   source type. See the {LibraryVersion} documentation for "Implementing
+      #   a Custom Library Source"
+      # 
+      # Prepares a library to be displayed by the server. This callback is 
+      # performed before each request on a library to ensure that it is loaded
+      # and ready to be viewed. If any steps need to be performed prior to loading,
+      # they are performed through this method (though they should be implemented
+      # through the +load_yardoc_from_SOURCE+ method).
+      # 
+      # @raise [LibraryNotPreparedError] if the library is not ready to be
+      #   displayed. Usually when raising this error, you would simultaneously
+      #   begin preparing the library for subsequent requests, although this
+      #   is not necessary.
       def prepare!
         return if yardoc_file
         meth = "load_yardoc_from_#{source}"
         send(meth) if respond_to?(meth)
       end
       
+      # @return [Gem::Specification] a gemspec object for a given library. Used
+      #   for :gem source types.
+      # @return [nil] if there is no installed gem for the library
       def gemspec
         ver = version ? "= #{version}" : ">= 0"
         Gem.source_index.find_name(name, ver).first
@@ -45,10 +175,19 @@ module YARD
       
       protected
 
+      # Called when a library of source type "disk" is to be prepared. In this
+      # case, the {#yardoc_file} should already be set, so nothing needs to be
+      # done.
       def load_yardoc_from_disk
         nil
       end
       
+      # Called when a library of source type "gem" is to be prepared. In this
+      # case, the {#yardoc_file} needs to point to the correct location for
+      # the installed gem. The yardoc file is built if it has not been done.
+      # 
+      # @raise [LibraryNotPreparedError] if the gem does not have an existing
+      #   yardoc file.
       def load_yardoc_from_gem
         require 'rubygems'
         ver = version ? "= #{version}" : ">= 0"
@@ -67,10 +206,12 @@ module YARD
         end
       end
       
+      # @return [String] the source path for a disk source
       def source_path_for_disk
         File.dirname(yardoc_file) if yardoc_file
       end
       
+      # @return [String] the source path for a gem source
       def source_path_for_gem
         gemspec.full_gem_path if gemspec
       end

data/lib/yard/server/rack_adapter.rb

@@ -3,24 +3,57 @@ require 'webrick/httputils'
 
 module YARD
   module Server
+    # This class wraps the {RackAdapter} into a Rack-compatible middleware.
+    # See {#initialize} for a list of options to pass via Rack's +#use+ method.
+    # 
+    # @note You must pass a +:libraries+ option to the RackMiddleware via +#use+. To
+    #   read about how to return a list of libraries, see {LibraryVersion} or look
+    #   at the example below.
+    # @example Using the RackMiddleware in a Rack application
+    #   libraries = {:mylib => [YARD::Server::LibraryVersion.new('mylib', nil, '/path/to/.yardoc')]}
+    #   use YARD::Server::RackMiddleware, :libraries => libraries
+    # 
     class RackMiddleware
+      # Creates a new Rack-based middleware for serving YARD documentation.
+      # 
+      # @param app the next Rack middleware in the stack
+      # @option opts [Hash{String=>Array<LibraryVersion>}] :libraries ({}) 
+      #   the map of libraries to serve through the adapter. This option is *required*.
+      # @option opts [Hash] :options ({}) a list of options to pass to the adapter.
+      #   See {Adapter#options} for a list.
+      # @option opts [Hash] :server_options ({}) a list of options to pass to the server.
+      #   See {Adapter#server_options} for a list.
       def initialize(app, opts = {})
         args = [opts[:libraries] || {}, opts[:options] || {}, opts[:server_options] || {}]
-        @app = RackAdapter.new(*args)
+        @app = app
+        @adapter = RackAdapter.new(*args)
       end
       
-      def call(env) @app.call(env) end
+      def call(env)
+        status, headers, body = *@adapter.call(env)
+        if status == 404
+          @app.call(env)
+        else
+          [status, headers, body]
+        end
+      end
     end
     
+    # A server adapter to respond to requests using the Rack server infrastructure.
     class RackAdapter < Adapter
       include WEBrick::HTTPUtils
       
+      # Responds to Rack requests and builds a response with the {Router}.
+      # @return [Array(Number,Hash,Array)] the Rack-style response
       def call(env)
         request = Rack::Request.new(env)
         request.path_info = unescape(request.path_info) # unescape things like %3F
         router.call(request)
       end
       
+      # Starts the +Rack::Server+. This method will pass control to the server and
+      # block.
+      # @return [void]
       def start
         server = Rack::Server.new(server_options)
         server.instance_variable_set("@app", self)

data/lib/yard/server/router.rb

@@ -1,17 +1,54 @@
 module YARD
   module Server
+    # A router class implements the logic used to recognize a request for a specific
+    # URL and run specific {Commands::Base commands}.
+    # 
+    # == Subclassing Notes
+    # To create a custom router, subclass this class and pass it into the adapter
+    # options through {Adapter#initialize} or by directly modifying {Adapter#router}. 
+    # 
+    # The most general customization is to change the URL prefixes recognized by 
+    # routing, which can be done by overriding {#docs_prefix}, {#list_prefix} 
+    # and {#search_prefix}.
+    # 
+    # == Implementing Custom Caching
+    # By default, the Router class performs static disk-based caching on all
+    # requests through the +#check_static_cache+. To override this behaviour,
+    # or create your own caching mechanism, mixin your own custom module with
+    # this method implemented as per {StaticCaching#check_static_cache}.
+    # 
+    # @example Creating a subclassed router
+    #   # Adds 'my' to all routing prefixes
+    #   class MyRouter < YARD::Server::Router
+    #     def docs_prefix; 'mydocs' end
+    #     def list_prefix; 'mylist' end
+    #     def search_prefix; 'mysearch' end
+    #   end
+    # 
+    #   # Using it:
+    #   WebrickAdapter.new(libraries, :router => MyRouter).start
     class Router
       include StaticCaching
       include Commands
       
+      # @return [Adapter Dependent] the request data coming in with the routing
       attr_accessor :request
       
+      # @return [Adapter] the adapter used by the router
       attr_accessor :adapter
       
+      # Creates a new router for a specific adapter
+      # 
+      # @param [Adapter] adapter the adapter to route requests to
       def initialize(adapter)
         self.adapter = adapter
       end
       
+      # Perform routing on a specific request, serving the request as a static
+      # file through {Commands::StaticFileCommand} if no route is found.
+      # 
+      # @param [Adapter Dependent] request the request object
+      # @return [Array(Number,Hash,Array)] the Rack-style server response data
       def call(request)
         self.request = request
         if result = (check_static_cache || route)
@@ -20,11 +57,20 @@ module YARD
           StaticFileCommand.new(adapter.options).call(request)
         end
       end
+      
+      # @group Route Prefixes
 
+      # @return [String] the URI prefix for all object documentation requests
       def docs_prefix; 'docs' end
+      
+      # @return [String] the URI prefix for all class/method/file list requests
       def list_prefix; 'list' end
+      
+      # @return [String] the URI prefix for all search requests
       def search_prefix; 'search' end
       
+      # @group Routing Methods
+      
       # @return [Array(LibraryVersion, Array<String>)] the library followed
       #   by the rest of the path components in the request path. LibraryVersion
       #   will be nil if no matching library was found.
@@ -42,8 +88,13 @@ module YARD
         [library, paths]
       end
 
-      private
+      protected
       
+      # Performs routing algorithm to find which prefix is called, first
+      # parsing out library name/version information.
+      # 
+      # @return [Array(Numeric,Hash,Array<String>)] the Rack-style response
+      # @return [nil] if no route is matched
       def route
         path = request.path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
         return route_index if path.empty? || path == docs_prefix
@@ -62,6 +113,10 @@ module YARD
         nil
       end
       
+      # Routes requests from {#docs_prefix} and calls the appropriate command
+      # @param [LibraryVersion] library the library to route for
+      # @param [Array<String>] paths path components (split by '/')
+      # @return (see #route)
       def route_docs(library, paths)
         return route_index if library.nil?
         case paths.first
@@ -78,6 +133,8 @@ module YARD
         cmd.call(request)
       end
       
+      # Routes for the index of a library / multiple libraries
+      # @return (see #route)
       def route_index
         if adapter.options[:single_library]
           route_docs(adapter.libraries.values.first.first, [])
@@ -86,6 +143,9 @@ module YARD
         end
       end
       
+      # Routes requests from {#list_prefix} and calls the appropriate command
+      # @param (see #route_docs)
+      # @return (see #route_docs)
       def route_list(library, paths)
         return if paths.empty?
         case paths.shift
@@ -97,11 +157,21 @@ module YARD
         cmd.new(final_options(library, paths)).call(request)
       end
       
+      # Routes requests from {#search_prefix} and calls the appropriate command
+      # @param (see #route_docs)
+      # @return (see #route_docs)
       def route_search(library, paths)
         return unless paths.empty?
         SearchCommand.new(final_options(library, paths)).call(request)
       end
       
+      # @group Utility Methods
+      
+      # Adds extra :library/:path option keys to the adapter options.
+      # Use this method when passing options to a command.
+      # 
+      # @param (see #route_docs)
+      # @return [Hash] finalized options
       def final_options(library, paths)
         adapter.options.merge(:library => library, :path => paths.join('/'))
       end