Source

amp / tasks / yard.rake

Full commit
##################################################################
#                  Licensing Information                         #
#                                                                #
#  The following code is licensed, as standalone code, under     #
#  the Ruby License, unless otherwise directed within the code.  #
#                                                                #
#  For information on the license of this code when distributed  #
#  with and used in conjunction with the other modules in the    #
#  Amp project, please see the root-level LICENSE file.          #
#                                                                #
#  © Michael J. Edgar and Ari Brown, 2009-2010                   #
#                                                                #
##################################################################

require 'yard'
require 'pp'

# YARD support
# yard is our documentation tool

# so that we can sort them
class YARD::CodeObjects::MethodObject
  def <=>(other)
    self.path <=> other.path
  end
end

namespace :yard do
  
  desc 'Force a rebuild of the documentation'
  YARD::Rake::YardocTask.new :full_doc do |yard|
    yard.options = ["--private", "--protected", "--quiet", "--readme=README.md"]
    yard.files = ["-", "SCHEDULE.markdown", "AUTHORS", "STYLE", "TODO.markdown", "LICENSE"]
  end
    
  YARD::Rake::YardocTask.new :doc do |yard|
    yard.options = ['--no-output', '--private', '--protected', '--use-cache']
  end
    
  def docd_method_percent(klass)
    total  = klass.meths.size.to_f
    undocd = klass.meths.select {|m| m.docstring.empty? }.size.to_f
    
    undocd.zero? ? 0.0 : (undocd / total)
  end
  
  # rake yard:search[ranks]
  desc 'Search the methods for the specified tag'
  task :search => [ :doc ]
  task :search, :tag do |task, args|
    tag = args[:tag]
    methods = YARD::Registry.all(:method)
    
    meths = methods.select do |m|
      m.tags.any? {|t| t.text.include? tag }
    end
    
    puts meths.sort
  end
  
  desc 'Find undocumented methods'
  task :undocd => [ :doc ] do
    methods = YARD::Registry.all(:method)
    meths = methods.select {|m| m.docstring.empty? }
    puts meths.sort
  end
  
  desc 'Put the list of methods and their parameters.'
  task :undocd_params => [ :doc ] do
    methods = YARD::Registry.all(:method)
    missing_params = []
    methods.each do |meth|
      meth.parameters.each do |name, default|
        next if name.to_s =~ /options/ #@options will remove the param for it
        found = false
        meth.tags.each do |tag|
          if tag.tag_name.to_s == "param" && tag.name.to_s == name.to_s
            found = true
            break
          end
        end
        missing_params << meth.path + " argument: #{name}" unless found
      end
    end
    puts missing_params.inspect
  end
  
  desc 'Find the classes with the highest percent on documented methods'
  task :percent_undocd => [ :doc ] do
    klasses = YARD::Registry.all(:class)
    
    ks     = klasses.map {|k| [k, docd_method_percent(k)] }
    sorted = ks.sort {|(_, percent), (_, percent2)| percent <=> percent2 }
    sorted.each do |(k, p)|
      puts "#{k} => #{p * 100}%" unless p == 0.0
    end
  end
  
  
end