yard 0.6.3 → 0.6.4

data/lib/yard.rb

@@ -1,5 +1,5 @@
 module YARD
-  VERSION = "0.6.3"
+  VERSION = "0.6.4"
   
   # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))

data/lib/yard/autoload.rb

@@ -135,10 +135,20 @@ module YARD
   end
   
   # Namespace for classes and modules that handle serving documentation over HTTP
+  # 
+  # == Implementing a Custom Server
+  # To customize the YARD server, see the {Adapter} and {Router} classes. 
+  # 
+  # == Rack Middleware
+  # If you want to use the YARD server as a Rack middleware, see the documentation
+  # in {RackMiddleware}.
+  # 
   # @since 0.6.0
   module Server
     require __p('server')
 
+    # Commands implement specific kinds of server responses which are routed
+    # to by the {Router} class. To implement a custom command, subclass {Commands::Base}.
     module Commands
       autoload :Base,                 __p('server/commands/base')
       autoload :DisplayFileCommand,   __p('server/commands/display_file_command')

data/lib/yard/cli/yri.rb

@@ -49,7 +49,7 @@ module YARD
       def run(*args)
         optparse(*args)
         
-        if Config::CONFIG['host_os'] =~ /mingw|win32/
+        if ::Config::CONFIG['host_os'] =~ /mingw|win32/
           @serializer ||= YARD::Serializers::StdoutSerializer.new
         else
           @serializer ||= YARD::Serializers::ProcessSerializer.new('less')
@@ -190,4 +190,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/code_objects/base.rb

@@ -388,7 +388,7 @@ module YARD
       # @return [String] the unique path of the object
       # @see #sep
       def path
-        if parent && !parent.root?
+        @path ||= if parent && !parent.root?
           [parent.path, name.to_s].join(sep)
         else
           name.to_s

data/lib/yard/code_objects/method_object.rb

@@ -45,6 +45,7 @@ module YARD::CodeObjects
     def scope=(v) 
       reregister = @scope ? true : false
       YARD::Registry.delete(self) if reregister
+      @path = nil
       @scope = v.to_sym 
       YARD::Registry.register(self) if reregister
     end
@@ -124,7 +125,7 @@ module YARD::CodeObjects
     # (they should still have a separator as a prefix).
     # @return [String] the path of a method
     def path
-      if !namespace || namespace.path == "" 
+      @path ||= if !namespace || namespace.path == "" 
         sep + super
       else
         super

data/lib/yard/code_objects/root_object.rb

@@ -3,8 +3,8 @@ module YARD
     # Represents the root namespace object (the invisible Ruby module that
     # holds all top level modules, class and other objects).
     class RootObject < ModuleObject
-      def path; "" end
-      def inspect; "#<yardoc root>" end
+      def path; @path ||= "" end
+      def inspect; @inspect ||= "#<yardoc root>" end
       def root?; true end
       def equal?(other)
         other == :root ? true : super(other)

data/lib/yard/parser/ruby/ast_node.rb

@@ -321,10 +321,6 @@ module YARD
         def namespace
           Array.new flatten[0...-1]
         end
-        
-        def source
-          super.split(/\s+/).first
-        end
       end
       
       class ParameterNode < AstNode

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -27,6 +27,7 @@ module YARD
           @source = source
           @tokens = []
           @comments = {}
+          @heredoc_tokens = []
           @map = {}
           @ns_charno = 0
           @list = []
@@ -88,6 +89,7 @@ module YARD
           :string_literal => [:tstring_beg, :heredoc_beg],
           :super => "super",
           :symbol => :symbeg,
+          :top_const_ref => "::",
           :undef => "undef",
           :unless => "unless",
           :until => "until",
@@ -218,8 +220,13 @@ module YARD
         def add_token(token, data)
           if @tokens.last && @tokens.last[0] == :symbeg
             @tokens[-1] = [:symbol, ":" + data]
+          elsif token == :heredoc_end
+            @heredoc_tokens << [@tokens.pop, [token, data]]
           else
             @tokens << [token, data]
+            if token == :nl && @heredoc_tokens.size > 0
+              @tokens += @heredoc_tokens.pop
+            end
           end
         end
 
@@ -281,6 +288,23 @@ module YARD
           visit_ns_token(:rbracket, tok, false)
         end
         
+        def on_top_const_ref(*args)
+          type = :top_const_ref
+          node = AstNode.node_class_for(type).new(type, args)
+          mapping = @map[MAPPINGS[type]]
+          extra_op = mapping.last[1] + 2 == charno ? mapping.pop : nil
+          lstart, sstart = *mapping.pop
+          node.source_range = Range.new(sstart, args.last.source_range.last)
+          node.line_range = Range.new(lstart, args.last.line_range.last)
+          mapping.push(extra_op) if extra_op
+          node
+        end
+        
+        def on_const_path_ref(*args)
+          klass = AstNode.node_class_for(:const_path_ref)
+          klass.new(:const_path_ref, args, listline: lineno..lineno, listchar: charno..charno)
+        end
+        
         [:if_mod, :unless_mod, :while_mod].each do |kw|
           node_class = AstNode.node_class_for(kw)
           module_eval(<<-eof, __FILE__, __LINE__ + 1)
@@ -298,7 +322,12 @@ module YARD
         end
         
         def on_string_literal(*args)
-          visit_event_arr AstNode.new(:string_literal, args)
+          node = visit_event_arr(AstNode.new(:string_literal, args))
+          if @source[charno, 1] !~ /["']/
+            nsr = node.source_range
+            node.source_range = Range.new(nsr.first, nsr.last + 1) 
+          end
+          node
         end
         
         def on_lambda(*args)

data/lib/yard/server/adapter.rb

@@ -1,30 +1,73 @@
 module YARD
   module Server
+    
+    # Short circuits a request by raising an error. This exception is caught
+    # by {Commands::Base#call} to immedaitely end a request and return a response.
     class FinishRequest < RuntimeError; end
+    
+    # Raises an error if a resource is not found. This exception is caught by
+    # {Commands::Base#call} to immediately end a request and return a 404 response
+    # code. If a message is provided, the body is set to the exception message.
     class NotFoundError < RuntimeError; end
 
+    # This class implements the bridge between the {Router} and the server
+    # backend for a specific server type. YARD implements concrete adapters
+    # for WEBrick and Rack respectively, though other adapters can be made
+    # for other server architectures.
+    # 
+    # == Subclassing Notes
+    # To create a concrete adapter class, implement the {#start} method to
+    # initiate the server backend.
+    # 
+    # @abstract
     class Adapter
-      # @return [String] the location where static files are located, if any
+      # @return [String] the location where static files are located, if any.
+      #   To set this field on initialization, pass +:DocumentRoot+ to the
+      #   +server_opts+ argument in {#initialize}
       attr_accessor :document_root
       
+      # @return [Hash{String=>Array<LibraryVersion>}] a map of libraries.
+      # @see LibraryVersion LibraryVersion for information on building a list of libraries
+      # @see #add_library
       attr_accessor :libraries
       
+      # @return [Hash] options passed and processed by adapters. The actual
+      #   options mostly depend on the adapters themselves.
       attr_accessor :options
       
+      # @return [Hash] a set of options to pass to the server backend. Note
+      #   that +:DocumentRoot+ also sets the {#document_root}.
       attr_accessor :server_options
       
+      # @return [Router] the router object used to route URLs to commands
       attr_accessor :router
 
+      # Performs any global initialization for the adapter.
+      # @note If you subclass this method, make sure to call +super+.
+      # @return [void]
       def self.setup
         Templates::Template.extra_includes |= [YARD::Server::DocServerHelper]
         Templates::Engine.template_paths |= [File.dirname(__FILE__) + '/templates']
       end
 
+      # Performs any global shutdown procedures for the adapter.
+      # @note If you subclass this method, make sure to call +super+.
+      # @return [void]
       def self.shutdown
         Templates::Template.extra_includes -= [YARD::Server::DocServerHelper]
         Templates::Engine.template_paths -= [File.dirname(__FILE__) + '/templates']
       end
       
+      # Creates a new adapter object
+      # 
+      # @param [Hash{String=>Array<LibraryVersion>}] libs a list of libraries,
+      #   see {#libraries} for formulating this list.
+      # @param [Hash] opts extra options to pass to the adapter
+      # @option opts [Class] :router (Router) the router class to initialize as the
+      #   adapter's router.
+      # @option opts [Boolean] :caching (false) whether or not caching is enabled
+      # @option opts [Boolean] :single_library (false) whether to server documentation
+      #   for a single or multiple libraries (changes URL structure)
       def initialize(libs, opts = {}, server_opts = {})
         self.class.setup
         self.libraries = libs
@@ -38,11 +81,17 @@ module YARD
         log.debug "Document root: #{document_root}" if document_root
       end
       
+      # Adds a library to the {#libraries} mapping for a given library object.
+      # @example Adding a new library to an adapter
+      #   adapter.add_library LibraryVersion.new('mylib', '1.0', '/path/to/.yardoc')
+      # @param [LibraryVersion] library a library to add
       def add_library(library)
         libraries[library.name] ||= []
         libraries[library.name] |= [library]
       end
       
+      # Implement this method to connect your adapter to your server.
+      # @abstract
       def start
         raise NotImplementedError
       end

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

@@ -3,10 +3,47 @@ require 'fileutils'
 module YARD
   module Server
     module Commands
+      # This is the base command class used to implement custom commands for
+      # a server. A command will be routed to by the {Router} class and return
+      # a Rack-style response.
+      # 
+      # == Attribute Initializers
+      # All attributes can be initialized via options passed into the {#initialize}
+      # method. When creating a custom command, the {Adapter#options} will 
+      # automatically be mapped to attributes by the same name on your class.
+      # 
+      #   class MyCommand < Base
+      #     attr_accessor :myattr
+      #   end
+      # 
+      #   Adapter.new(libs, {:myattr => 'foo'}).start
+      #   
+      #   # when a request comes in, cmd.myattr == 'foo'
+      # 
+      # == Subclassing Notes
+      # To implement a custom command, override the {#run} method, not {#call}.
+      # In your implementation, you should set the body and status for requests.
+      # See details in the +#run+ method documentation.
+      # 
+      # Note that if your command deals directly with libraries, you should
+      # consider subclassing the more specific {LibraryCommand} class instead.
+      # 
+      # @abstract
+      # @see #run
       class Base
+        # @group Basic Command and Adapter Options
+        
         # @return [Hash] the options passed to the command's constructor
         attr_accessor :command_options
         
+        # @return [Adapter] the server adapter
+        attr_accessor :adapter
+
+        # @return [Boolean] whether to cache
+        attr_accessor :caching
+        
+        # @group Attributes Set Per Request
+
         # @return [Request] request object
         attr_accessor :request
         
@@ -16,18 +53,24 @@ module YARD
         # @return [Hash{String => String}] response headers
         attr_accessor :headers
 
-        # @return [Numeric] status code
+        # @return [Numeric] status code. Defaults to 200 per request
         attr_accessor :status
 
-        # @return [String] the response body
+        # @return [String] the response body. Defaults to empty string.
         attr_accessor :body
         
-        # @return [Adapter] the server adapter
-        attr_accessor :adapter
-        
-        # @return [Boolean] whether to cache
-        attr_accessor :caching
+        # @group Instance Method Summary
 
+        # Creates a new command object, setting attributes named by keys 
+        # in the options hash. After initialization, the options hash
+        # is saved in {#command_options} for further inspection.
+        # 
+        # @example Creating a Command
+        #   cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)
+        #   cmd.library # => mylib
+        #   cmd.command_options # => {:caching => true, :library => mylib}
+        # @param [Hash] opts the options hash, saved to {#command_options}
+        #   after initialization.
         def initialize(opts = {})
           opts.each do |key, value|
             send("#{key}=", value) if respond_to?("#{key}=")
@@ -35,6 +78,13 @@ module YARD
           self.command_options = opts
         end
 
+        # The main method called by a router with a request object.
+        # 
+        # @note This command should not be overridden by subclasses. Implement
+        #   the callback method {#run} instead.
+        # @param [Adapter Dependent] request the request object
+        # @return [Array(Number,Hash,Array<String>)] a Rack-style response
+        #   of status, headers, and body wrapped in an array.
         def call(request)
           self.request = request
           self.path ||= request.path[1..-1]
@@ -51,20 +101,61 @@ module YARD
           not_found if status == 404
           [status, headers, body.is_a?(Array) ? body : [body]]
         end
+        
+        # @group Abstract Methods
 
+        # Subclass this method to implement a custom command. This method
+        # should set the {#status} and {#body}, and optionally modify the 
+        # {#headers}. Note that +#status+ defaults to 200.
+        # 
+        # @example A custom command
+        #   class ErrorCommand < Base
+        #     def run
+        #       self.body = 'ERROR! The System is down!'
+        #       self.status = 500
+        #       self.headers['Conten-Type'] = 'text/plain'
+        #     end
+        #   end
+        #       
+        # @abstract
+        # @return [void]
         def run
           raise NotImplementedError
         end
+
+        protected
         
-        def not_found
-          return unless body.empty?
-          self.body = "Not found: #{request.path}"
-          self.headers['Content-Type'] = 'text/plain'
-          self.headers['X-Cascade'] = 'pass'
-        end
+        # @group Helper Methods
         
-        protected
+        # Renders a specific object if provided, or a regular template rendering
+        # if object is not provided.
+        # 
+        # @todo This method is dependent on +#options+, it should be in {LibraryCommand}.
+        # @param [CodeObjects::Base, nil] object calls {CodeObjects::Base#format} if
+        #   an object is provided, or {Templates::Engine.render} if object is nil. Both
+        #   receive +#options+ as an argument.
+        # @return [String] the resulting output to display
+        def render(object = nil)
+          case object
+          when CodeObjects::Base
+            cache object.format(options)
+          when nil
+            cache Templates::Engine.render(options)
+          else
+            cache object
+          end
+        end
         
+        # Override this method to implement custom caching mechanisms for
+        # 
+        # @example Caching to memory
+        #   $memory_cache = {}
+        #   def cache(data)
+        #     $memory_cache[path] = data
+        #   end
+        # @param [String] data the data to cache
+        # @return [String] the same cached data (for chaining)
+        # @see StaticCaching
         def cache(data)
           if caching && adapter.document_root
             path = File.join(adapter.document_root, request.path.sub(/\.html$/, '') + '.html')
@@ -76,17 +167,20 @@ module YARD
           self.body = data
         end
 
-        def render(object = nil)
-          case object
-          when CodeObjects::Base
-            cache object.format(options)
-          when nil
-            cache Templates::Engine.render(options)
-          else
-            cache object
-          end
+        # Sets the body and headers (but not status) for a 404 response. Does
+        # nothing if the body is already set.
+        # 
+        # @return [void]
+        def not_found
+          return unless body.empty?
+          self.body = "Not found: #{request.path}"
+          self.headers['Content-Type'] = 'text/plain'
+          self.headers['X-Cascade'] = 'pass'
         end
 
+        # Sets the headers and status code for a redirection to a given URL
+        # @param [String] url the URL to redirect to
+        # @raise [FinishRequest] causes the request to terminate.
         def redirect(url)
           headers['Location'] = url
           self.status = 302

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

@@ -1,6 +1,9 @@
 module YARD
   module Server
     module Commands
+      # Displays a README or extra file.
+      # 
+      # @todo Implement better support for detecting binary (image) filetypes
       class DisplayFileCommand < LibraryCommand
         def run
           ppath = library.source_path