chrisjpowers-rdoc_metric 0.1.2

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Chris Powers
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+ 
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,26 @@
+= RdocMetric
+
+<em>A gem for analyzing how much of your Ruby code is documented with Rdoc.</em>
+
+Developed by Chris Powers (http://github.com/chrisjpowers)
+
+Version 0.1 -- September 10, 2009
+
+The RdocMetric class parses through ruby files and determines how 
+well documented they are. It looks for an rdoc comment for
+each class, module, method, attribute and constant declaration to
+determine if documentation exists.
+
+The gem installs the <tt>rdoc_metric</tt> command line program. You
+can use it without any arguments to parse all the ruby files in the
+current directory and all subdirectories, or you can pass it a 
+specific path.
+
+  $ rdoc_metric
+
+or
+
+  $ rdoc_metric my_app/app/models # only parses .rb files in models dir
+
+So far this is a very rudimentary implementation, so please feel
+free to fork and improve!

data/bin/rdoc_metric

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby -wKU
+
+require 'rubygems'
+require 'rdoc_metric'
+
+path = File.join(ARGV.first || '.', '**', '*.rb')
+
+puts RdocMetric.new(path).to_s

data/lib/rdoc_metric.rb

@@ -0,0 +1,108 @@
+# Developed by Chris Powers (http://github.com/chrisjpowers)
+# Version 0.1 -- September 10, 2009
+# 
+# The RdocMetric class parses through ruby files and determines how 
+# well documented they are. It looks for a comment on the line before
+# each class, module, method, attribute and constant declaration to
+# determine if documentation exists.
+# 
+# Calling the #to_s method will output a list of all the parsed files,
+# displaying how many of each declaration were documented, along with
+# an overall percentage of coverage.
+# 
+# Currently there is no weight given to classes vs. methods vs. constants,
+# the percentage is simply based on the overall entity count.
+# 
+class RdocMetric
+  
+  # Accepts a path that is sent to Dir.glob
+  # 
+  # Ex: <tt>RdocMetric.new("/apps/my_app/**/*.rb")
+  def initialize(path)
+    files = Dir.glob(path)
+    @files = files.map {|f| RdocFile.new(f) }
+  end
+  
+  # The overall percentage of coverage as an integer
+  def score
+    @files.inject(0) {|sum, file| sum += file.score } / @files.length
+  end
+  
+  # Outputs the full listing of rdoc coverage for all parsed files.
+  def to_s
+    out = "* * * Total Rdoc Coverage: #{score}% * * *\n\n"
+    return out + @files.map(&:to_s).join("\n") + "\n" + out
+  end
+  
+  
+  # models a single parsed file
+  class RdocFile
+    def initialize(filepath)
+      @filepath = filepath
+      @methods = []
+      @classes = []
+      @modules = []
+      @attrs = []
+      @constants = []
+      parse_file!
+    end
+    
+    # Percentage of rdoc coverage for this file as an Integer
+    def score
+      total = 0
+      docs = 0
+      [@classes, @modules, @methods, @constants, @attrs].each do |collection|
+        collection.each do |item|
+          total += 1
+          docs += 1 if item
+        end
+      end
+      return 100 if total == 0
+      return ((docs.to_f / total) * 100).to_i
+    end
+    
+    # Outputs the coverage breakdown message for this file.
+    def to_s
+      out  = "Rdoc Coverage for #{@filepath}: #{score}%\n"
+      out += "  Classes: #{@classes.select{|c| c }.length}/#{@classes.length}\n" unless @classes.empty?
+      out += "  Modules: #{@modules.select{|c| c }.length}/#{@modules.length}\n" unless @modules.empty?
+      out += "  Methods: #{@methods.select{|c| c }.length}/#{@methods.length}\n" unless @methods.empty?
+      out += "  Attributes: #{@attrs.select{|c| c }.length}/#{@attrs.length}\n" unless @attrs.empty?
+      out += "  Constants: #{@constants.select{|c| c }.length}/#{@constants.length}\n" unless @constants.empty?
+      out
+    end
+    
+    private
+    
+    # Parses through file, adds true or false entries into collections
+    # as it encounters documented and undocumented declarations, respectively
+    def parse_file!
+      File.open(@filepath, 'r') do |f|
+        last_line = ''
+        while this_line = f.gets
+          coll = case this_line
+            when /^\s*def /     : @methods
+            when /^\s*class /   : @classes
+            when /^\s*module /  : @modules
+            when /^\s*(attr_reader|attr_accessor|attr_writer) / : @attrs
+            when /^\s*[^a-z =]+\s*=/ : @constants
+            else nil
+          end
+          # add a true entry if comment precedes declaration or follows on same line
+          coll << is_comment?(last_line) || has_comment?(this_line) if coll
+          last_line = this_line
+        end
+      end
+    end
+    
+    # Does the line start with a # ?
+    def is_comment?(line)
+      line =~ /^\s*#/
+    end
+    
+    # Does the line have a # anywhere on it?
+    def has_comment?(line)
+      line =~ /#[^{]/
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: chrisjpowers-rdoc_metric
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+platform: ruby
+authors: 
+- Chris Powers
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-10 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: RdocMetric analyzes the Rdoc coverage of Ruby files.
+email: chrisjpowers@gmail.com
+executables: 
+- rdoc_metric
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- bin/rdoc_metric
+- lib/rdoc_metric.rb
+has_rdoc: true
+homepage: http://github.com/chrisjpowers/rdoc_metric
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --quiet
+- --title
+- RdocMetric documentation
+- --opname
+- index.html
+- --line-numbers
+- --main
+- README.rdoc
+- --inline-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: RdocMetric analyzes the Rdoc coverage of Ruby files.
+test_files: []
+