inch 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56294f89d5505f0a2a580505884d549ce0a56692
-  data.tar.gz: b665c48327c4c9f1e92c3a99c9a85b6130063f07
+  metadata.gz: b7567dd076efa1061ed2fe78515e1cae97bacd0c
+  data.tar.gz: d56dc92a462fab56c73d1693f091aec50b29ca62
 SHA512:
-  metadata.gz: 71bd9be4a5870d7ad7e42f77eb99d19305eb9e06e914cf8ac0a532a0fac413f77aaf373f9defd10b12de4defc5f8b76ea63b34857e09aac52e7f32958ff73d6f
-  data.tar.gz: 10437fbaebbecd3d1edf526af898115288cd5743ec04673f31b58aa323b50b3f684b6fbc1883a7370a31ca85fee519c4c51e3cafa0880ab76ad9177e1a904b41
+  metadata.gz: fac873dedadc24c9d3430d2c60b921bd1b3ab16a7797ab37aca149b56897b28e53bcd021b7569fb56c1a29b3f31c12a0c72150b8092e49a40e4a1383738442d6
+  data.tar.gz: d3648df680260a3c7c9d450f372db7ff5eeb2477d3f9feef31f6b3380d08a6291cb295a263fe291cd91fbbbc11491fc2878f35896ae8c3e931dfb364349fa826

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in inch.gemspec
 gemspec
+
+gem 'simplecov', :require => false, :group => :test

data/README.md

@@ -1,6 +1,12 @@
 # Inch
 
-TODO: Write a gem description
+Inch is a documentation measurement tool for Ruby, based on
+[YARD](http://yardoc.org/).
+
+It does not measure documentation *coverage*, but grades and
+prioritizes code objects to give you hints where to improve your docs.
+One Inch at a time.
+
 
 ## Installation
 
@@ -16,14 +22,340 @@ Or install it yourself as:
 
     $ gem install inch
 
+
 ## Usage
 
-TODO: Write usage instructions here
+To run Inch, simply type
+
+    $ inch
+
+Given a `lib` directory with the following code inside:
+
+    class Foo
+      # A complicated method
+      def complicated(o, i, *args, &block)
+        # ... snip ...
+      end
+
+      # An example of a method that takes a parameter (+param1+)
+      # and does nothing.
+      #
+      # Returns nil
+      def nothing(param1)
+      end
+
+      def filename
+        "#{self.class}_#{id}.foo"
+      end
+    end
+
+Inch will suggest that the docs could be improved:
+
+    # Properly documented, could be improved:
+
+    ┃  B  ↑  Foo#complicated
+
+    # Undocumented:
+
+    ┃  U  ↑  Foo
+    ┃  U  ↗  Foo#filename
+
+    You might want to look at these files:
+
+    ┃ lib/foo.rb
+
+    Grade distribution (undocumented, C, B, A):  █  ▁ ▄ ▄
+
+    Only considering priority objects: ↑ ↗ →  (use `--help` for options).
+
+Inch does not report coverage scores for code objects. It assigns grades and shows you the grade distribution rather then an overall grade.
+
+The grades (A, B, C) show how good the present documentation seems. The grade `U` is assigned to all undocumented objects. The arrows (↑ ↗ → ↘ ↓) hint at the importance of the object being documented.
+
+
+### Inch does not judge
+
+Inch uses grades instead of scores to take a more relaxed approach. You can
+get an `A` without employing every trick from a predetermined list of checks.
+
+The reason for using the grade distribution instead of an overall score is
+that the distribution says more about your codebase than a coverage percentage
+ever could:
+
+    Grade distribution (undocumented, C, B, A):  ▄  ▁ ▄ █
+
+In this example we have a good chunk of code that is still undocumented, but
+the vast majority of code is rated A or B. This tells you three things:
+
+* There is a significant amount of documentation present.
+* The present documentation seems good.
+* There are still undocumented methods.
+
+Inch does not really tell you what to do from here. It suggests objects and
+files that could be improved to get a better rating, but that is all.
+
+This way, it is perfectly reasonable to leave parts of your codebase
+undocumented. Instead of reporting
+
+    coverage: 67.1%  46 ouf of 140 checks failed
+
+and leaving you with a bad feeling, Inch tells you there are still
+undocumented objects without judging.
+
+Inch does not tell you to document all your methods. Neither does it tell you
+not to. It does not tell you "a method's documentation should be a single line
+under 80 characters not ending in a period".
+
+
+
+### Limitations
+
+How you document your code is up to you and Inch can't actually tell you how good your docs are.
+
+It can't tell if your code examples work or if you described parameters
+correctly or if you have just added `# TODO: write docs` to each and every
+method.
+
+It is just a tool, that you can use to find parts of a codebase lacking
+documentation.
+
+
+
+## Features
+
+Inch is build to parse [YARD](http://yardoc.org/),
+[RDoc](http://rdoc.rubyforge.org/) and [TomDoc](http://tomdoc.org/)
+style documentation comments, but works reasonably well with unstructured
+comments.
+
+It comes with four sub-commands: `suggest`, `stats`, `show`, and `list`
+
+
+
+### inch suggest
+
+Suggests places where a codebase suffers a lack of documentation.
+
+    $ inch suggest
+
+    # Properly documented, could be improved:
+
+    ┃  B  ↑  Inch::CLI::Command::BaseObject#prepare_objects
+    ┃  B  ↑  Inch::CLI::Command::BaseList#prepare_list
+    ┃  B  ↑  Inch::CLI::Command::Suggest#run
+    ┃  B  ↑  Inch::CLI::Command::List#run
+    ┃  B  ↑  Inch::CodeObject::Proxy::MethodParameterObject#initialize
+    ┃  B  ↗  Inch::CLI::Command::Stats#run
+    ┃  B  ↗  Inch::CLI::CommandParser#run
+    ┃  B  ↗  Inch::CLI::CommandParser.run
+
+    # Not properly documented:
+
+    ┃  C  ↑  Inch::CodeObject::NodocHelper#implicit_nodoc_comment?
+    ┃  C  ↑  Inch::CLI::Command::Output::Console#initialize
+    ┃  C  ↑  Inch::CLI::Command::Output::Suggest#initialize
+    ┃  C  ↑  Inch::Rake::Suggest#initialize
+
+    # Undocumented:
+
+    ┃  U  ↑  Inch::Evaluation::NamespaceObject#evaluate
+    ┃  U  ↑  Inch::Evaluation::ConstantObject#evaluate
+    ┃  U  ↑  Inch::Evaluation::MethodObject#evaluate
+    ┃  U  ↑  Inch::SourceParser#find_object
+
+    You might want to look at these files:
+
+    ┃ lib/inch/code_object/proxy/base.rb
+    ┃ lib/inch/code_object/proxy/method_object.rb
+    ┃ lib/inch/evaluation/role/constant.rb
+    ┃ lib/inch/evaluation/role/method_parameter.rb
+    ┃ lib/inch/evaluation/role/object.rb
+
+    Grade distribution (undocumented, C, B, A):  █  ▃ ▁ ▄
+
+    Only considering priority objects: ↑ ↗ →  (use `--help` for options).
+
+
+
+### inch stats
+
+Shows you an overview of the codebase.
+
+    $ inch stats
+
+    Grade distribution: (undocumented, C, B, A)
+
+      Overall:  █  ▂ ▁ ▃    439 objects
+
+    Grade distribution by priority:
+
+            ↑   ▁  ▄ █ ▁     10 objects
+
+            ↗   █  ▃ ▁ ▃    302 objects
+
+            →   ▆  ▂ ▁ █     73 objects
+
+            ↘   █  ▁ ▁ ▁     54 objects
+
+            ↓   ▁  ▁ ▁ ▁      0 objects
+
+    Priority distribution in grades: (low to high)
+
+          ↓      ↘      →      ↗      ↑
+      U:  ▁ ▁ ▁ ▁ ▁ ▁ ▂ ▂ ▁ █ ▁ ▁ ▁ ▁ ▁   243 objects
+
+      C:  ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ █ ▁ ▁ ▁ ▁ ▁    73 objects
+
+      B:  ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ █ ▂ ▄ ▁ ▁ ▁    19 objects
+
+      A:  ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▄ ▁ █ ▁ ▁ ▁ ▁ ▁   104 objects
+
+
+    Try `--format json|yaml` for raw numbers.
+
+
+
+### inch show
+
+Shows you details about what can be approved in a specific object.
+
+    $ inch show Inch::SourceParser#find_object
+
+    # Inch::SourceParser#find_object
+
+    ┃ -> lib/inch/source_parser.rb:16
+    ┃ ------------------------------------------------------
+    ┃ Grade: C - Needs work
+    ┃ ------------------------------------------------------
+    ┃ + Add a comment describing the method
+    ┃ + Describe the parameter 'path'
+    ┃ + Describe the return type of 'find_object'
+    ┃ + Add a code example (optional)
+    ┃ ------------------------------------------------------
+
+
+
+### inch list
+
+Lists all objects in your codebase with their grades.
+
+    $ inch list
+
+    # Seems really good
+
+    ┃  A  ↑  Inch::CLI::Command::Output::Console#object
+    ┃  A  ↗  Inch
+    ┃  A  ↗  Inch::CodeObject::Proxy::Base#depth
+    ┃  A  ↗  Inch::CodeObject::Proxy::Base#height
+    ┃  A  ↗  Inch::CLI::Command::Base#description
+    ┃  A  ↗  Inch::CodeObject::NodocHelper#nodoc?
+    ┃  A  ↗  Inch::CLI::YardoptsHelper#parse_yardopts_options
+    ┃  A  ↗  Inch::Evaluation::NamespaceObject
+    ┃  A  ↗  Inch::SourceParser
+    ┃  A  ↗  Inch::Evaluation::ScoreRange#range=
+    ┃ ...  (omitting 75 objects)
+
+    # Proper documentation present
+
+    ┃  B  ↑  Inch::CLI::Command::Suggest#run
+    ┃  B  ↑  Inch::CLI::Command::List#run
+    ┃  B  ↑  Inch::CodeObject::Proxy::MethodParameterObject#initialize
+    ┃  B  ↗  Inch::CLI::Command::Stats#run
+    ┃  B  ↗  Inch::CLI::CommandParser#run
+    ┃  B  ↗  Inch::CLI::CommandParser.run
+    ┃  B  ↗  Inch::CLI::Command::Base.run
+    ┃  B  ↗  Inch::Evaluation::Base#object=
+    ┃  B  ↗  Inch::CodeObject::Proxy::Base#object=
+
+    # Needs work
+
+    ┃  C  ↑  Inch::CLI::Command::Output::Stats#initialize
+    ┃  C  ↑  Inch::CLI::Command::Output::Suggest#initialize
+    ┃  C  ↑  Inch::CodeObject::NodocHelper#implicit_nodoc_comment?
+    ┃  C  ↑  Inch::CLI::Command::Output::Console#initialize
+    ┃  C  ↑  Inch::Evaluation::NamespaceObject#evaluate
+    ┃  C  ↑  Inch::Evaluation::ConstantObject#evaluate
+    ┃  C  ↑  Inch::SourceParser#find_object
+    ┃  C  ↑  Inch::Evaluation::MethodObject#evaluate
+    ┃  C  ↗  Inch::CLI::Command::Show#run
+    ┃  C  ↗  Inch::CodeObject::Proxy::Base
+    ┃ ...  (omitting 248 objects)
+
+    This output omitted 323 objects. Use `--all` to display all objects.
+
+
+
+### Rake task
+
+Add this to your `Rakefile`:
+
+    require 'inch/rake'
+
+    Inch::Rake::Suggest.new
+
+This creates a rake task named `inch`. Change the name by passing it to the constructor. Use the `args` config option to add any command-line arguments from `inch suggest --help`.
+
+    require 'inch/rake'
+
+    Inch::Rake::Suggest.new("doc:suggest") do |suggest|
+      suggest.args << "--private"
+    end
+
+
+
+## How is this different from ...?
+
+### Documentation coverage
+
+Documentation coverage checks (like they can be found in
+[cane](https://github.com/square/cane) and
+[rubocop](https://github.com/bbatsov/rubocop)) look at all code objects and
+determine if the found documentation meets a certain threshold/expectation.
+
+Inch takes a different approach as it aims for "properly documented" rather
+than "100% coverage".
+
+### Yardstick
+
+[Yardstick](https://github.com/dkubb/yardstick) is a tool that verifies
+documentation coverage of Ruby code and is specifically designed for
+[YARD-style documentation](http://yardoc.org/). It is a great tool to see
+where your docs could benefit from YARD's extra features over RDoc, but, at
+the same time, it is very overwhelming when applied to a codebase that does
+not yet adhere to YARD's standards.
+
+Inch takes a less YARD specific, more "relaxed" approach: It recognizes
+different forms of documentation (even in the same codebase) and assigns
+grades instead of coverage measurements. So you can get an "A" rating without
+employing every technique YARD has to offer.
+
+
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/inch/fork )
+1. [Fork it!](http://github.com/rrrene/inch/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+
+
+## Author
+
+René Föhring (@rrrene)
+
+
+
+## Credits
+
+Inch would not exist without Loren Segal's [YARD](http://yardoc.org/).
+
+
+
+## License
+
+Inch is released under the MIT License. See the LICENSE.txt file for further
+details.
+
+For YARD's licensing, see YARD's README under http://yardoc.org/

data/Rakefile

@@ -1 +1,9 @@
 require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = "test/**/*_test.rb"
+end
+
+task :default => :test

data/TODOS.md

@@ -0,0 +1,12 @@
+# TODOs
+
+* Recognize all relevant options in .yardopts file
+  * --plugin
+  * --[no-]api API
+* Provide reusable context that filters code objects according to the
+  visibility options
+* Add support for multiple signatures for methods
+  (realized via the @overload tag in YARD)
+* YARD assigns an implicit @return tag to methods ending in a question
+  mark -- maybe this is a problem since those methods appear as `C` in
+  the output, even if they don't have any other documentation

data/bin/inch

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'bundler'
+begin
+  Bundler.require
+rescue Bundler::GemfileNotFound
+ensure
+  require 'inch'
+end
+
+# hit Control + C to stop
+Signal.trap("INT") do
+  warn "  cancelled by user (INT)"
+  exit 1
+end
+
+Inch::CLI::CommandParser.run(*ARGV)

data/inch.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = Inch::VERSION
   spec.authors       = ["René Föhring"]
   spec.email         = ["rf@bamaru.de"]
-  spec.summary       = %q{Wrapper for YARD}
-  spec.description   = %q{Wrapper for YARD}
+  spec.summary       = %q{Documentation measurement tool for Ruby}
+  spec.description   = %q{Documentation measurement tool for Ruby, based on YARD.}
   spec.homepage      = ""
   spec.license       = "MIT"
 
@@ -20,4 +20,9 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "rake"
+
+  spec.add_dependency "yard", "~> 0.8.7"
+  spec.add_dependency "term-ansicolor"
+  spec.add_dependency 'sparkr', "~> 0.2.0"
+  spec.add_dependency "pry"
 end

data/lib/inch.rb

@@ -1,5 +1,10 @@
 require "inch/version"
 
 module Inch
-  # Your code goes here...
 end
+
+require_relative 'inch/core_ext'
+require_relative 'inch/source_parser'
+require_relative 'inch/code_object'
+require_relative 'inch/evaluation'
+require_relative 'inch/cli'