yardoc.rb in yard-0.4.0

- old
+ new

@@ -1,72 +1,115 @@
 require 'optparse'
 
 module YARD
   module CLI
     class Yardoc
+      # The configuration filename to load extra options from
       DEFAULT_YARDOPTS_FILE = ".yardopts"
       
-      attr_reader :options, :visibilities
-      attr_accessor :files, :reload, :generate
+      # @return [Hash] the hash of options passed to the template.
+      # @see Templates::Engine#render
+      attr_reader :options
+      
+      # @return [Array<String>] list of Ruby source files to process
+      attr_accessor :files
+      
+      # @return [Boolean] whether to reparse the source files even if the 
+      #   .yardoc already exists.
+      attr_accessor :reload
+      
+      # @return [Boolean] whether to generate output
+      attr_accessor :generate
+      
+      # The options file name (defaults to {DEFAULT_YARDOPTS_FILE})
+      # @return [String] the filename to load extra options from
       attr_accessor :options_file
       
+      # Helper method to create an instance and run the utility
+      # @see #run
       def self.run(*args) new.run(*args) end
         
+      # Creates a new instance of the commandline utility
       def initialize
         @options = SymbolHash[
           :format => :html, 
           :template => :default, 
+          :markup => :rdoc,
           :serializer => YARD::Serializers::FileSystemSerializer.new, 
           :files => [],
-          :verifier => lambda do |gen, obj| 
-            return false if gen.respond_to?(:visibility) && !visibilities.include?(gen.visibility) 
-          end
+          :visibilities => [:public],
+          :verifier => nil
         ]
         @files = []
-        @visibilities = [:public]
         @reload = true
         @generate = true
         @options_file = DEFAULT_YARDOPTS_FILE
       end
       
+      # Runs the commandline utility, parsing arguments and generating
+      # output if set.
+      # 
+      # @param [Array<String>] args the list of arguments
+      # @return [nil] 
       def run(*args)
         args += support_rdoc_document_file!
         optparse(*yardopts)
         optparse(*args)
         Registry.load(files, reload)
         
         if generate
-          Generators::FullDocGenerator.new(options).generate(all_objects)
+          Templates::Engine.generate(all_objects, options)
         end
+        
+        true
       end
 
+      # The list of all objects to process. Override this method to change
+      # which objects YARD should generate documentation for.
+      # 
+      # @return [Array<CodeObjects::Base>] a list of code objects to process
       def all_objects
         Registry.all(:root, :module, :class)
       end
       
+      # Parses the .yardopts file for default yard options
+      # @return [nil] 
       def yardopts
         IO.read(options_file).split(/\s+/)
       rescue Errno::ENOENT
         []
       end
       
       private
       
+      # Reads a .document file in the directory to get source file globs
+      # @return [nil] 
       def support_rdoc_document_file!
         IO.read(".document").split(/\s+/)
       rescue Errno::ENOENT
         []
       end
       
+      # Adds a set of extra documentation files to be processed
+      # @param [Array<String>] files the set of documentation files
       def add_extra_files(*files)
         files.map! {|f| f.include?("*") ? Dir.glob(f) : f }.flatten!
         files.each do |file|
           raise Errno::ENOENT, "Could not find extra file: #{file}" unless File.file?(file)
           options[:files] << file
         end
       end
       
+      # Parses the file arguments into Ruby files and extra files, which are
+      # separated by a '-' element.
+      # 
+      # @example Parses a set of Ruby source files
+      #   parse_files %w(file1 file2 file3)
+      # @example Parses a set of Ruby files with a separator and extra files
+      #   parse_files %w(file1 file2 - extrafile1 extrafile2)
+      # @param [Array<String>] files the list of files to parse
+      # @return [nil] 
       def parse_files(*files)
         self.files = []
         seen_extra_files_marker = false
         
         files.each do |file|
@@ -81,11 +124,20 @@
             self.files << file
           end
         end
       end
       
+      # @param [Array<String>] expressions a list of query expressions to
+      #   turn into a proc
+      def add_verifier(*expressions)
+        
+      end
+      
+      # Parses commandline options.
+      # @param [Array<String>] args each tokenized argument
       def optparse(*args)
+        query_expressions = []
         serialopts = SymbolHash.new
         
         opts = OptionParser.new
         opts.banner = "Usage: yardoc [options] [source_files [- extra_files]]"
 
@@ -129,25 +181,33 @@
 
         opts.separator ""
         opts.separator "Output options:"
   
         opts.on('--no-public', "Don't show public methods. (default shows public)") do 
-          visibilities.delete(:public)
+          options[:visibilities].delete(:public)
         end
 
         opts.on('--protected', "Show or don't show protected methods. (default hides protected)") do
-          visibilities.push(:protected)
+          options[:visibilities].push(:protected)
         end
 
         opts.on('--private', "Show or don't show private methods. (default hides private)") do 
-          visibilities.push(:private) 
+          options[:visibilities].push(:private) 
         end
+        
+        opts.on('--no-private', "Hide objects with @private tag") do
+          query_expressions << '!@private'
+        end
 
         opts.on('--no-highlight', "Don't highlight code in docs as Ruby.") do 
           options[:no_highlight] = true
         end
         
+        opts.on('--query QUERY', "Only show objects that match a specific query") do |query|
+          query_expressions << query.taint
+        end
+        
         opts.on('--title TITLE', 'Add a specific title to HTML documents') do |title|
           options[:title] = title
         end
 
         opts.on('-r', '--readme FILE', '--main FILE', 'The readme file used as the title page of documentation.') do |readme|
@@ -180,11 +240,11 @@
           options[:template] = template.to_sym
         end
 
         opts.on('-p', '--template-path PATH', 
                 'The template path to look for templates in. (used with -t).') do |path|
-          YARD::Generators::Base.register_template_path(path)
+          YARD::Templates::Engine.register_template_path(path)
         end
         
         opts.on('-f', '--format FORMAT', 
                 'The output format for the template. (defaults to html)') do |format|
           options[:format] = format
@@ -206,11 +266,13 @@
         end
         
         # Last minute modifications
         parse_files(*args) unless args.empty?
         self.files = ['lib/**/*.rb'] if self.files.empty?
-        self.visibilities.uniq!
+        options[:verifier] = Verifier.new(*query_expressions) unless query_expressions.empty?
+        options[:visibilities].uniq!
         options[:serializer] ||= Serializers::FileSystemSerializer.new(serialopts)
+        options[:readme] ||= Dir.glob('README*').first
       end
     end
   end
 end