inch 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a3d046495aa235b1de7a7b672064aa637bd234a9
-  data.tar.gz: 8c1f011bbae79bebace8b24652bc8d4a91e03423
+  metadata.gz: 76a30cfdd0b22157bc5ef102e9f15cc96ec40147
+  data.tar.gz: 21d1a3ecb2c12294579f4406059a322e25fb15ff
 SHA512:
-  metadata.gz: da0b420bda2854141896e838ab0cb399110415370ceffdc026e686017a796389bd29f66fb4e085d617e42fc30c5e234e436f49b234270b7690fe67000121a549
-  data.tar.gz: a56f9672e84f23952719ea7c2087aa08ae736ed5b7e20c24f612066abc5fed6dc145e252c11cceae797c4fcb7a138a37a3a04373534ad5b9f1147d47a81580de
+  metadata.gz: e60ae99656807e6731978c0b3bd29534ad313bcda1f8aabae5407dc062bb8aa3f1e589f3599b900f917973608047d1e6909bdfc52e872792d07e281b18cda16f
+  data.tar.gz: 5bd8e9097b64d1cb9e454ef47e052e1d96ca1d2f562d2c12c9ae470b26de4db456e6c901563f5c9b9267eb013a6976ee25c2f31f768577806e826d6bf6be3b79

data/README.md

@@ -1,9 +1,16 @@
 # Inch [![Build Status](https://travis-ci.org/rrrene/inch.png)](https://travis-ci.org/rrrene/inch)
 
-Take a look at the project page for an [introduction with screenshots (live and in full color)](http://rrrene.github.io/inch/).
+`inch` gives you hints where to improve your docs. One Inch at a time.
 
-Inch is a documentation measurement tool for the Ruby programming language
-that gives you hints where to improve your docs. One Inch at a time.
+Take a look at the [project page with screenshots (live and in full color)](http://rrrene.github.io/inch/).
+
+## What can it do?
+
+`inch` is a little bit like Code Climate, but for your inline code documentation (and not a webservice).
+
+It is a command-line utility that suggests places in your codebase where documentation can be improved. 
+
+If there are no inline-docs yet, `inch` can tell you where to start.
 
 
 
@@ -31,93 +38,126 @@ To run Inch, simply type
 
 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
+```ruby
+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.
+## Philosophy
+
+Inch was created to help people document their code, therefore it may be more important to look at **what it does not** do than at what it does.
+
+* It does not aim for "fully documented" or "100% documentation coverage".
+* It does not tell you to document all your code (neither does it tell you not to).
+* It does not impose rules on how your documentation should look like.
+* It does not require that, e.g."every method's documentation should be a single line under 80 characters not ending in a period" or that "every class and module should provide a code example of their usage".
+
+Inch takes a more relaxed approach towards documentation measurement and tries to show you places where your codebase *could* use more documentation.
+
+
+
+### The Grade System
+
+Inch assigns grades to each class, module, constant or method in a codebase, based on how complete the docs are.
+
+The grades are:
+
+* `A` - Seems really good
+* `B` - Properly documented, but could be improved
+* `C` - Needs work
+* `U` - Undocumented
+
+Using this system has some advantages compared to plain coverage scores:
+
+* You can get an `A` even if you "only" get 90 out of 100 possible points.
+* Getting a `B` is basically good enough.
+* Undocumented objects are assigned a special grade, instead of scoring 0%.
+
+The last point might be the most important one: If objects are undocumented, there is nothing to evaluate. Therefore you can not simply give them a bad rating, because they might be left undocumented intentionally.
+
+
+
+### Priorities ↑ ↓
+
+Every class, module, constant and method in a codebase is assigned a priority which reflects how important Inch thinks it is to be documented.
 
+This process follows some reasonable rules, like
 
-### Inch does not judge
+* it is more important to document public methods than private ones
+* it is more important to document methods with many parameters than methods without parameters
+* it is not important to document objects marked as `:nodoc:`
 
-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.
+Priorities are displayed as arrows. Arrows pointing north mark high priority objects, arrows pointing south mark low priority objects.
 
-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:
+
+
+### No overall scores or grades
+
+Inch does not give you a grade for your whole codebase.
+
+"Why?" you might ask. Look at the example below:
 
     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:
+In this example there is a part 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.
+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. 
 
-This way, it is perfectly reasonable to leave parts of your codebase
-undocumented. Instead of reporting
+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.
+This provides a lot more insight than an overall grade could, because an overall grade for the above example would either be an `A` (if the evaluation ignores undocumented objects) or a weak `C` (if the evaluation includes them).
 
-It is just a tool, that you can use to find parts of a codebase lacking
-documentation.
+The grade distribution does a much better job of painting the bigger picture.
 
 
 
@@ -128,8 +168,67 @@ Inch is build to parse [YARD](http://yardoc.org/),
 style documentation comments, but works reasonably well with unstructured
 comments.
 
-It comes with four sub-commands: `suggest`, `stats`, `show`, and `list`
+These inline-docs below all score an `A` despite being written in different styles:
+
+```ruby
+# Detects the size of the blob.
+#
+# @example
+#   blob_size(filename, blob) # => some value
+#
+# @param filename [String] the filename
+# @param blob [String] the blob data
+# @param mode [String, nil] optional String mode
+# @return [Fixnum,nil]
+def blob_size(filename, blob, mode = nil)
+```
+
+```ruby
+# Detects the size of the blob.
+#
+#   blob_size(filename, blob) # => some value
+#
+# Params:
+# +filename+:: String filename
+# +blob+:: String blob data
+# +mode+:: Optional String mode (defaults to nil)
+def blob_size(filename, blob, mode = nil)
+```
+
+```ruby
+# Public: Detects the size of the blob.
+#
+# filename - String filename
+# blob - String blob data
+# mode - Optional String mode (defaults to nil)
+#
+# Examples
+#
+#   blob_size(filename, blob)
+#   # => some value
+#
+# Returns Fixnum or nil.
+def blob_size(filename, blob, mode = nil)
+```
+
+
+But you don't have to adhere to any specific syntax. This gets an `A` as well:
+
+```ruby
+# Returns the size of a +blob+ for a given +filename+.
+#
+#   blob_size(filename, blob)
+#   # => some value
+#
+def blob_size(filename, blob, mode = nil)
+```
+
+Inch *let's you write your documentation the way you want*.
+
+
+## Subcommands
 
+It comes with four sub-commands: `suggest`, `stats`, `show`, and `list`
 
 
 ### inch suggest
@@ -278,6 +377,21 @@ This creates a rake task named `inch`. Change the name by passing it to the cons
 
 
 
+
+
+## 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 in your codebase that are
+lacking documentation.
+
+
+
 ## How is this different from ...?
 
 ### Documentation coverage

data/TODOS.md

@@ -9,10 +9,4 @@
   (realized via the @overload tag in YARD)
 
 * Think about implicit cases in terms of evaluation:
-  * constructors and ?-methods are automatically assigned a @return tag
   * attr_* methods are automatically assigned a docstring and @param tag
-
-* Think about limiting the number of `B`-objects in `inch suggest`
-  `inch suggest` shows too many `B`s even though there are still undocumented
-  objects in the codebase. this becomes a problem, when one thinks of `B` as
-  "good enough", which Inch itself suggests.

data/config/defaults.rb

@@ -0,0 +1,82 @@
+Inch::Config.run do
+  # development!
+
+  evaluation do
+    grade(:A) do
+      scores    80..100
+      label     "Seems really good"
+      color     :green
+    end
+
+    grade(:B) do
+      scores    50...80
+      label     "Proper documentation present"
+      color     :yellow
+    end
+
+    grade(:C) do
+      scores    1...50
+      label     "Needs work"
+      color     :red
+    end
+
+    grade(:U) do
+      scores    0..0
+      label     "Undocumented"
+      color     :color141
+      bg_color  :color105
+    end
+
+    schema(:ConstantObject) do
+      docstring           1.0
+
+      # optional:
+      unconsidered_tag    0.2
+    end
+
+    schema(:ClassObject) do
+      docstring           1.0
+
+      # optional:
+      code_example_single 0.1
+      code_example_multi  0.2
+      unconsidered_tag    0.2
+    end
+
+    schema(:ModuleObject) do
+      docstring           1.0
+
+      # optional:
+      code_example_single 0.1
+      code_example_multi  0.2
+      unconsidered_tag    0.2
+    end
+
+    schema(:MethodObject) do
+      docstring           0.5
+      parameters          0.4
+      return_type         0.1
+      return_description  0.3
+
+      if object.constructor? || object.questioning_name?
+        parameters          parameters + return_type
+        return_type         0.0
+      end
+      
+      if object.constructor?
+        return_description  0.0
+      end
+
+      if !object.has_parameters? || object.setter?
+        return_description  docstring + parameters
+        docstring           docstring + parameters
+        parameters          0.0
+      end
+
+      # optional:
+      code_example_single 0.1
+      code_example_multi  0.25
+      unconsidered_tag    0.2
+    end
+  end
+end

data/lib/inch/cli/command/base.rb

@@ -50,6 +50,15 @@ module Inch
           command
         end
 
+        # Registers the current Command in the CommandParser
+        #
+        # @param name [Symbol] name of the Command
+        # @return [void]
+        def self.register_command_as(name, default = false)
+          CLI::CommandParser.default_command = name if default
+          CLI::CommandParser.commands[name] = self
+        end
+
         def initialize
           options_class = "Command::Options::#{self.class.to_s.split('::').last}"
           @options = eval(options_class).new

data/lib/inch/cli/command/base_list.rb

@@ -14,10 +14,10 @@ module Inch
 
         def initialize
           super
-          @ranges = Evaluation.new_score_ranges
+          @grade_lists = Evaluation.new_grade_lists
         end
 
-        # Prepares the list of objects and ranges, parsing arguments and
+        # Prepares the list of objects and grade_lists, parsing arguments and
         # running the source parser.
         #
         # @param *args [Array<String>] the list of arguments.
@@ -27,17 +27,17 @@ module Inch
           @options.verify
           run_source_parser(@options.paths, @options.excluded)
           filter_objects
-          assign_objects_to_ranges
+          assign_objects_to_grade_lists
         end
 
         private
 
-        # Assigns the objects returned by {#objects} to the score ranges in
-        # +@ranges+ based on their score
+        # Assigns the objects returned by {#objects} to the grade_lists
+        # based on their score
         #
-        def assign_objects_to_ranges
-          @ranges.each do |range|
-            list = objects.select { |o| range.range.include?(o.score) }
+        def assign_objects_to_grade_lists
+          @grade_lists.each do |range|
+            list = objects.select { |o| range.scores.include?(o.score) }
             range.objects = sort_by_priority(list)
           end
         end

data/lib/inch/cli/command/base_object.rb

@@ -15,7 +15,7 @@ module Inch
 
         def initialize
           super
-          @ranges = Evaluation.new_score_ranges
+          @grade_lists = Evaluation.new_grade_lists
         end
 
         # Prepares the given objects, parsing arguments and

data/lib/inch/cli/command/list.rb

@@ -1,7 +1,12 @@
+require_relative 'options/list'
+require_relative 'output/list'
+
 module Inch
   module CLI
     module Command
       class List < BaseList
+        register_command_as :list
+
         def description
           'Lists all objects with their results'
         end
@@ -17,7 +22,7 @@ module Inch
         # @return [void]
         def run(*args)
           prepare_list(*args)
-          Output::List.new(@options, objects, @ranges)
+          Output::List.new(@options, objects, @grade_lists)
         end
       end
     end

data/lib/inch/cli/command/options/base.rb

@@ -101,7 +101,7 @@ module Inch
           #
           # @return [String]
           def description_hint_grades
-            grades = Evaluation.new_score_ranges.map(&:grade)
+            grades = Evaluation::Grade.all
             "School grades (#{grades.join(', ')}) are assigned and " +
               "displayed with each object."
           end

data/lib/inch/cli/command/options/suggest.rb

@@ -8,6 +8,7 @@ module Inch
 
           attribute :proper_grades, [:A, :B]
           attribute :grades_to_display, [:B, :C, :U]
+          attribute :grade_weights, [0.2, 0.4, 0.4]
           attribute :object_min_priority, 0
           attribute :object_max_score, ::Inch::Evaluation::Base::MAX_SCORE
 
@@ -49,7 +50,8 @@ module Inch
               @object_max_score = object_max_score - 1
               # only A-listers are regarded as 'proper'
               @proper_grades = [:A]
-              @grades_to_display = [:A, :B, :C]
+              @grades_to_display = [:A, :B, :C, :U]
+              @grade_weights = [0.3, 0.3, 0.2, 0.2]
               @object_count = 30
               @pedantic = true
             end

data/lib/inch/cli/command/output/list.rb

@@ -7,10 +7,10 @@ module Inch
 
           PER_RANGE = 10
 
-          def initialize(options, objects, ranges)
+          def initialize(options, objects, grade_lists)
             @options = options
             @objects = objects
-            @ranges = ranges
+            @grade_lists = grade_lists
             @omitted = 0
 
             display_list
@@ -19,13 +19,13 @@ module Inch
           private
 
           def display_list
-            @ranges.each do |range|
+            @grade_lists.each do |range|
               if range.objects.empty?
                 # pass
               else
                 trace
-                trace_header(range.description, range.color, range.bg_color)
-                display_range(range)
+                trace_header(range.label, range.color, range.bg_color)
+                display_grade_list(range)
               end
             end
 
@@ -36,7 +36,7 @@ module Inch
             end
           end
 
-          def display_range(range)
+          def display_grade_list(range)
             display_count = @options.show_all? ? range.objects.size : PER_RANGE
             list = range.objects[0...display_count]
             list.each do |o|

data/lib/inch/cli/command/output/show.rb

@@ -68,9 +68,9 @@ module Inch
           end
 
           def grade(score)
-            ranges ||= Evaluation.new_score_ranges
-            r = ranges.detect { |r| r.range.include?(score) }
-            "#{r.grade} - #{r.description}".color(r.color)
+            grade_lists ||= Evaluation.new_grade_lists
+            r = grade_lists.detect { |r| r.scores.include?(score) }
+            "#{r.grade} - #{r.label}".color(r.color)
           end
         end
       end