inch 0.6.4 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 97a2e0db4145398867af07819d6657c6473c7cf2
-  data.tar.gz: 288d4945533cde5327a6479d0c4225d8cdff562b
+  metadata.gz: 3f5e51a1fb3956e91d0e804c28cbfb8c21dc1ef9
+  data.tar.gz: fb07a2be558122b91bcb674381a3dbac81ab49e2
 SHA512:
-  metadata.gz: 0958cf52771d502deeaa704a0c976dc8f3adb758f114fec1a9cb5bd08be81d1a5ced6c7a42f5ce609003d727a79acda12e879fe798cf3cbab97956dab33e7cca
-  data.tar.gz: aa5badaa8ea8c48db207dfe9830a42c59086471f9bd314478753de0c54659eba7b485fd7a1358a8af4a187e51b13826629d30834e0779e5fd39ad2bacedeb24f
+  metadata.gz: c6708035951911b83cecfec2ff1c885e7b9cfd73b148c36e48d827ac63ba520ff6159f4be9c73880e7bdfe7d17079bfbdc10251dc76b7e4b243abbb7fc3c644b
+  data.tar.gz: 4c22485a4a3afa60aacaccc3be699737e34329c9ec168715547457131e29fc9fba881f99105bbe9db24f748f16cdd8319a13d3524615075009776d8a7454ecd1

data/.ruby-version

@@ -1 +1 @@
-ruby-2.1.3
+ruby-2.1.6

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.7.0
+
+BREAKING CHANGE:
+
+- CLI: Uses an exit status different from zero in case of suggestions. This might break workflows based on `&&` (e.g. `rake && inch && ...`).
+
+Improvements:
+
+- Elixir: Skip analysis for function parameters starting with '_'
+- JavaScript: Add support for @ignore and istanbul ignore comments
+- JavaScript: Add support for @also (multiple signatures)
+
 ## 0.6.4
 
 - Ruby: Skip analysis for method parameters named '_'
@@ -8,7 +20,7 @@
 ## 0.6.3
 
 - Elixir: Recognize callbacks and macros
-- NodeJS: Improve param type detection
+- JavaScript: Improve param type detection
 
 ## 0.6.2
 

data/README.md

@@ -260,7 +260,8 @@ It comes with four sub-commands: `suggest`, `stats`, `show`, and `list`
 
 ### inch suggest
 
-Suggests places where a codebase suffers a lack of documentation.
+Suggests places where a codebase suffers a lack of documentation. The command
+line exit status will be above zero when suggestions are found.
 
     $ inch suggest
 

data/bin/inch

@@ -20,4 +20,5 @@ $LOAD_PATH.unshift(find_lib_path)
 require 'inch'
 require 'inch/cli'
 
-Inch::CLI::CommandParser.run(*ARGV)
+command = Inch::CLI::CommandParser.run(*ARGV)
+exit(command.exit_status)

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

@@ -36,6 +36,8 @@ module Inch
       # @note This was adapted from YARD
       #   https://github.com/lsegal/yard/blob/master/lib/yard/cli/command.rb
       class Base
+        EXIT_STATUS_SUCCESS = 0
+
         include TraceHelper
 
         attr_reader :codebase # @return [Codebase::Proxy]
@@ -72,6 +74,14 @@ module Inch
           ''
         end
 
+        # Returns the exit status of the running command.
+        # This can be overridden to customize exit statusses.
+        #
+        # @return [Fixnum] zero (by default)
+        def exit_status
+          EXIT_STATUS_SUCCESS
+        end
+
         # Returns the name of the command by which it is referenced
         # in the command list
         #

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

@@ -7,6 +7,8 @@ module Inch
       class Suggest < List
         register_command_as :suggest, true
 
+        EXIT_CODE_PENDING_SUGGESTIONS = 10
+
         def description
           'Suggests some objects to be documented (better)'
         end
@@ -23,13 +25,19 @@ module Inch
         def run(*args)
           prepare_codebase(*args)
           context = API::Suggest.new(codebase, @options)
+          self.objects = context.objects
           if @options.format == Options::Suggest::FORMAT_TEXT
-            Output::Suggest.new(@options, context.all_objects, context.objects,
+            Output::Suggest.new(@options, context.all_objects, objects,
                                 context.grade_lists, context.files)
           else
             Output::Stats.new(@options, context.all_objects, context.grade_lists)
           end
         end
+
+        # @return [Fixnum] 10 if suggestions were found, zero otherwise
+        def exit_status
+          objects.empty? ? super : EXIT_CODE_PENDING_SUGGESTIONS
+        end
       end
     end
   end

data/lib/inch/cli/command_parser.rb

@@ -77,6 +77,7 @@ module Inch
           command = commands[command_name].new
           ui.trace format('  %-8s %s', command_name, command.description)
         end
+        exit 0
       end
 
       # Runs the {Command} object matching the command name of the first

data/lib/inch/language/elixir/code_object/function_parameter_object.rb

@@ -12,6 +12,7 @@ module Inch
             @attributes[key]
           end
 
+          IGNORE_NAME_PREFIX = "_"
           BAD_NAME_EXCEPTIONS = %w(id)
           BAD_NAME_THRESHOLD = 3
 
@@ -29,12 +30,12 @@ module Inch
 
           # @return [Boolean] +true+ if an additional description given?
           def described?
-            self[:described?]
+            self[:described?] || ignore?
           end
 
           # @return [Boolean] +true+ if the parameter is mentioned in the docs
           def mentioned?
-            self[:mentioned?]
+            self[:mentioned?] || ignore?
           end
 
           def name
@@ -49,7 +50,7 @@ module Inch
 
           # @return [Boolean] +true+ if the type of the parameter is defined
           def typed?
-            self[:typed?]
+            self[:typed?] || ignore?
           end
 
           def unnamed?
@@ -61,6 +62,12 @@ module Inch
           def wrongly_mentioned?
             self[:wrongly_mentioned?]
           end
+
+          private
+
+          def ignore?
+            name.start_with?(IGNORE_NAME_PREFIX)
+          end
         end
       end
     end

data/lib/inch/language/javascript/provider/jsdoc/object.rb

@@ -23,11 +23,11 @@ module Inch
               # @return [Provider::JSDoc::Object]
               def for(jsdoc_object)
                 @cache ||= {}
-                if (proxy_object = @cache[cache_key(jsdoc_object)])
+                key = cache_key(jsdoc_object)
+                if proxy_object = @cache[key]
                   proxy_object
                 else
-                  @cache[cache_key(jsdoc_object)] =
-                    class_for(jsdoc_object).new(jsdoc_object)
+                  @cache[key] = class_for(jsdoc_object).new(jsdoc_object)
                 end
               end
 

data/lib/inch/language/javascript/provider/jsdoc/object/base.rb

@@ -116,7 +116,9 @@ module Inch
               end
 
               def nodoc?
-                @hash['comment'] == false
+                @hash['comment'] == false ||
+                  docstring.tag?(:ignore) ||
+                    docstring.to_s.strip.start_with?("istanbul ignore")
               end
 
               def namespace?

data/lib/inch/language/javascript/provider/jsdoc/parser.rb

@@ -39,7 +39,7 @@ module Inch
             def objects
               @objects ||= parsed_objects.map do |o|
                 JSDoc::Object.for(o) unless IGNORE_TYPES.include?(o['kind'])
-              end.compact
+              end.compact.uniq
             end
 
             private

data/lib/inch/version.rb

@@ -1,3 +1,3 @@
 module Inch
-  VERSION = '0.6.4'
+  VERSION = '0.7.0'
 end

data/test/fixtures/javascript/inch_test/all.json

@@ -2,7 +2,7 @@
     "args": [],
     "branch_name": "master",
     "client_name": "inchjs",
-    "client_version": "0.1.4",
+    "client_version": "0.4.0",
     "git_repo_url": "git@github.com:inch-ci/Hello-World-NodeJS.git",
     "language": "javascript",
     "objects": [
@@ -74,11 +74,11 @@
                     "value": "function"
                 },
                 "filename": "inch_test.js",
-                "lineno": 13,
+                "lineno": 14,
                 "path": "/src",
                 "range": [
-                    165,
-                    236
+                    166,
+                    235
                 ]
             },
             "name": "generate_docs",
@@ -108,6 +108,54 @@
             "scope": "static",
             "undocumented": true
         },
+        {
+            "comment": "/*\n* @ignore\n*/",
+            "kind": "function",
+            "longname": "InchTest.Docs.Formatter.nodoc_ignore",
+            "memberof": "InchTest.Docs.Formatter",
+            "meta": {
+                "code": {
+                    "id": "astnode100000050",
+                    "name": "nodoc_ignore",
+                    "type": "FunctionExpression",
+                    "value": "function"
+                },
+                "filename": "inch_test.js",
+                "lineno": 25,
+                "path": "/src",
+                "range": [
+                    434,
+                    463
+                ]
+            },
+            "name": "nodoc_ignore",
+            "scope": "static",
+            "undocumented": true
+        },
+        {
+            "comment": "/* istanbul ignore next */",
+            "kind": "function",
+            "longname": "InchTest.Docs.Formatter.nodoc_istanbul",
+            "memberof": "InchTest.Docs.Formatter",
+            "meta": {
+                "code": {
+                    "id": "astnode100000053",
+                    "name": "nodoc_istanbul",
+                    "type": "FunctionExpression",
+                    "value": "function"
+                },
+                "filename": "inch_test.js",
+                "lineno": 27,
+                "path": "/src",
+                "range": [
+                    500,
+                    531
+                ]
+            },
+            "name": "nodoc_istanbul",
+            "scope": "static",
+            "undocumented": true
+        },
         {
             "comment": "/**\n*\n* This function takes `param1` and `param2` as arguments.\n*\n* @param {Number} param1 A number from 0 to 26 that will result in a letter a-z\n* @param {String} param2 A text\n* @return {String} A character from a-z based on the input number n\n*\n* Examples:\n*\n*   > InchTest.Naming.resource_name(MyApp.User)\n*   \"user\"\n*   > InchTest.Naming.resource_name(MyApp.UserView, \"View\")\n*   \"user\"\n*/",
             "description": "This function takes `param1` and `param2` as arguments.",
@@ -116,7 +164,7 @@
             "memberof": "InchTest.Functions",
             "meta": {
                 "code": {
-                    "id": "astnode100000057",
+                    "id": "astnode100000063",
                     "name": "InchTest.Functions.full_doc",
                     "paramnames": [
                         "param1",
@@ -126,11 +174,11 @@
                     "value": "function"
                 },
                 "filename": "inch_test.js",
-                "lineno": 41,
+                "lineno": 47,
                 "path": "/src",
                 "range": [
-                    841,
-                    914
+                    974,
+                    1047
                 ]
             },
             "name": "full_doc",
@@ -174,7 +222,7 @@
             "memberof": "InchTest.Functions",
             "meta": {
                 "code": {
-                    "id": "astnode100000070",
+                    "id": "astnode100000076",
                     "name": "InchTest.Functions.full_doc_second_parameter_unnamed",
                     "paramnames": [
                         "param1",
@@ -184,16 +232,146 @@
                     "value": "function"
                 },
                 "filename": "inch_test.js",
-                "lineno": 57,
+                "lineno": 63,
                 "path": "/src",
                 "range": [
-                    1271,
-                    1364
+                    1404,
+                    1497
                 ]
             },
             "name": "full_doc_second_parameter_unnamed",
             "scope": "static"
         },
+        {
+            "access": "public",
+            "comment": "/**\n* Creates and returns a new MultiRedisClient instance.\n*\n* @function\n* @memberof! MultiRedisClient\n* @public\n* @param {redis|Array} clients - The redis client/s\n* @returns {MultiRedisClient} The multiple redis client instance\n* @example\n* ```js\n* //create multiple redis clients\n* var redis = require('redis');\n* var client1 = redis.createClient(...);\n* var client2 = redis.createClient(...);\n*\n* //create the wrapper client\n* var MultipleRedis = require('multiple-redis');\n* var multiClient = MultipleRedis.createClient([client1, client2]);\n*\n* //run any command on the multi client instead of the original clients\n* multiClient.set('string key', 'string val', callback);\n* ```\n*\n*",
+            "description": "Creates and returns a new MultiRedisClient instance.",
+            "examples": [
+                "```js\n//create multiple redis clients\nvar redis = require('redis');\nvar client1 = redis.createClient(...);\nvar client2 = redis.createClient(...);\n\n//create the wrapper client\nvar MultipleRedis = require('multiple-redis');\nvar multiClient = MultipleRedis.createClient([client1, client2]);\n\n//run any command on the multi client instead of the original clients\nmultiClient.set('string key', 'string val', callback);\n```"
+            ],
+            "forceMemberof": true,
+            "kind": "function",
+            "longname": "MultiRedisClient.InchTest.Functions.multiple_signatures",
+            "memberof": "MultiRedisClient",
+            "meta": {
+                "code": {
+                    "id": "astnode100000089",
+                    "name": "InchTest.Functions.multiple_signatures",
+                    "paramnames": [],
+                    "type": "FunctionExpression",
+                    "value": "function"
+                },
+                "filename": "inch_test.js",
+                "lineno": 115,
+                "path": "/src",
+                "range": [
+                    3015,
+                    3082
+                ]
+            },
+            "name": "InchTest.Functions.multiple_signatures",
+            "params": [
+                {
+                    "description": "The redis client/s",
+                    "name": "clients",
+                    "type": {
+                        "names": [
+                            "redis",
+                            "Array"
+                        ]
+                    }
+                }
+            ],
+            "returns": [
+                {
+                    "description": "The multiple redis client instance",
+                    "type": {
+                        "names": [
+                            "MultiRedisClient"
+                        ]
+                    }
+                }
+            ],
+            "scope": "static"
+        },
+        {
+            "access": "public",
+            "comment": "\n*\n* @function\n* @memberof! MultiRedisClient\n* @public\n* @param {Array} connectionInfo - The redis client/s connection info\n* @param {string} connectionInfo.host - The redis host\n* @param {number} connectionInfo.post - The redis port\n* @param {Array} [options] - Used when this client creates the redis clients\n* @returns {MultiRedisClient} The multiple redis client instance\n* @example\n* ```js\n* //create the wrapper client with connection info\n* var MultipleRedis = require('multiple-redis');\n* var multiClient = MultipleRedis.createClient([{\n*   host: 'host1',\n*   port: 6379\n* }, {\n*   host: 'host2',\n*   port: 6379\n* }], options);\n*\n* //run any command on the multi client instead of the original clients\n* multiClient.set('string key', 'string val', callback);\n* ```\n*/",
+            "examples": [
+                "```js\n//create the wrapper client with connection info\nvar MultipleRedis = require('multiple-redis');\nvar multiClient = MultipleRedis.createClient([{\n  host: 'host1',\n  port: 6379\n}, {\n  host: 'host2',\n  port: 6379\n}], options);\n\n//run any command on the multi client instead of the original clients\nmultiClient.set('string key', 'string val', callback);\n```"
+            ],
+            "forceMemberof": true,
+            "kind": "function",
+            "longname": "MultiRedisClient.InchTest.Functions.multiple_signatures",
+            "memberof": "MultiRedisClient",
+            "meta": {
+                "code": {
+                    "id": "astnode100000089",
+                    "name": "InchTest.Functions.multiple_signatures",
+                    "paramnames": [],
+                    "type": "FunctionExpression",
+                    "value": "function"
+                },
+                "filename": "inch_test.js",
+                "lineno": 115,
+                "path": "/src",
+                "range": [
+                    3015,
+                    3082
+                ]
+            },
+            "name": "InchTest.Functions.multiple_signatures",
+            "params": [
+                {
+                    "description": "The redis client/s connection info",
+                    "name": "connectionInfo",
+                    "type": {
+                        "names": [
+                            "Array"
+                        ]
+                    }
+                },
+                {
+                    "description": "The redis host",
+                    "name": "connectionInfo.host",
+                    "type": {
+                        "names": [
+                            "string"
+                        ]
+                    }
+                },
+                {
+                    "description": "The redis port",
+                    "name": "connectionInfo.post",
+                    "type": {
+                        "names": [
+                            "number"
+                        ]
+                    }
+                },
+                {
+                    "description": "Used when this client creates the redis clients",
+                    "name": "options",
+                    "optional": true,
+                    "type": {
+                        "names": [
+                            "Array"
+                        ]
+                    }
+                }
+            ],
+            "returns": [
+                {
+                    "description": "The multiple redis client instance",
+                    "type": {
+                        "names": [
+                            "MultiRedisClient"
+                        ]
+                    }
+                }
+            ],
+            "scope": "static"
+        },
         {
             "comment": "/**\n*\n* This function takes no arguments.\n*\n* Examples:\n*\n*   > InchTest.Naming.resource_name(MyApp.User)\n*   \"user\"\n*   > InchTest.Naming.resource_name(MyApp.UserView, \"View\")\n*   \"user\"\n*/",
             "description": "This function takes no arguments.\n\nExamples:\n\n  > InchTest.Naming.resource_name(MyApp.User)\n  \"user\"\n  > InchTest.Naming.resource_name(MyApp.UserView, \"View\")\n  \"user\"",
@@ -202,17 +380,17 @@
             "memberof": "InchTest.CodeExamples",
             "meta": {
                 "code": {
-                    "id": "astnode100000088",
+                    "id": "astnode100000104",
                     "name": "single_code_example",
                     "type": "FunctionExpression",
                     "value": "function"
                 },
                 "filename": "inch_test.js",
-                "lineno": 74,
+                "lineno": 129,
                 "path": "/src",
                 "range": [
-                    1609,
-                    1665
+                    3325,
+                    3381
                 ]
             },
             "name": "single_code_example",
@@ -226,28 +404,21 @@
             "memberof": "InchTest.CodeExamples",
             "meta": {
                 "code": {
-                    "id": "astnode100000093",
+                    "id": "astnode100000109",
                     "name": "multiple_code_examples",
                     "type": "FunctionExpression",
                     "value": "function"
                 },
                 "filename": "inch_test.js",
-                "lineno": 95,
+                "lineno": 150,
                 "path": "/src",
                 "range": [
-                    2094,
-                    2153
+                    3810,
+                    3869
                 ]
             },
             "name": "multiple_code_examples",
             "scope": "static"
-        },
-        {
-            "files": [
-                "/home/rf/devel/Hello-World-NodeJS/src/inch_test.js"
-            ],
-            "kind": "package",
-            "longname": "package:undefined"
         }
     ]
 }

data/test/integration/cli/command/console_test.rb

@@ -12,6 +12,12 @@ describe ::Inch::CLI::Command::Console do
     @command = ::Inch::CLI::Command::Console
   end
 
+  it 'should run with exit status' do
+    _out, _err = capture_io do
+      assert_equal @command.run.exit_status, @command::EXIT_STATUS_SUCCESS
+    end
+  end
+
   it 'should output info when run with --help' do
     out, err = capture_io do
       assert_raises(SystemExit) { @command.run('--help') }

data/test/integration/cli/command/diff_test.rb

@@ -23,6 +23,12 @@ describe ::Inch::CLI::Command::Diff do
     FileUtils.rm_rf @tmp_dir
   end
 
+  it 'should run with exit status' do
+    _out, _err = capture_io do
+      assert_equal @command.run.exit_status, @command::EXIT_STATUS_SUCCESS
+    end
+  end
+
   it 'should not show any changes' do
     # this runs `inch diff` on a freshly cloned repo
     # should not show any changes

data/test/integration/cli/command/inspect_test.rb

@@ -6,6 +6,13 @@ describe ::Inch::CLI::Command::Inspect do
     @command = ::Inch::CLI::Command::Inspect
   end
 
+  it 'should run with exit status' do
+    _out, _err = capture_io do
+      cmd = @command.run('Foo::Bar#', '--no-color')
+      assert_equal cmd.exit_status, @command::EXIT_STATUS_SUCCESS
+    end
+  end
+
   it 'should warn and exit when run without args' do
     out, err = capture_io do
       assert_raises(SystemExit) { @command.run }

data/test/integration/cli/command/list_test.rb

@@ -9,6 +9,12 @@ describe ::Inch::CLI::Command::List do
 
   include Shared::BaseList
 
+  it 'should run with exit status' do
+    _out, _err = capture_io do
+      assert_equal @command.run.exit_status, @command::EXIT_STATUS_SUCCESS
+    end
+  end
+
   it 'should run without args' do
     out, err = capture_io do
       @command.run

data/test/integration/cli/command/show_test.rb

@@ -6,6 +6,13 @@ describe ::Inch::CLI::Command::Show do
     @command = ::Inch::CLI::Command::Show
   end
 
+  it 'should run with exit status' do
+    _out, _err = capture_io do
+      cmd = @command.run('Foo::Bar#', '--no-color')
+      assert_equal cmd.exit_status, @command::EXIT_STATUS_SUCCESS
+    end
+  end
+
   it 'should warn and exit when run without args' do
     out, err = capture_io do
       assert_raises(SystemExit) { @command.run }

data/test/integration/cli/command/stats_test.rb

@@ -6,6 +6,12 @@ describe ::Inch::CLI::Command::Stats do
     @command = ::Inch::CLI::Command::Stats
   end
 
+  it 'should run with exit status' do
+    _out, _err = capture_io do
+      assert_equal @command.run.exit_status, @command::EXIT_STATUS_SUCCESS
+    end
+  end
+
   it 'should run without args' do
     out, err = capture_io do
       @command.run

data/test/integration/cli/command/suggest_test.rb

@@ -7,6 +7,12 @@ describe ::Inch::CLI::Command::Suggest do
     @command = ::Inch::CLI::Command::Suggest
   end
 
+  it 'should run with exit status' do
+    _out, _err = capture_io do
+      assert_equal @command.run.exit_status, @command::EXIT_CODE_PENDING_SUGGESTIONS
+    end
+  end
+
   it 'should run without args' do
     out, err = capture_io do
       @command.run
@@ -93,6 +99,13 @@ describe ::Inch::CLI::Command::Suggest do
 
   # Edge case: Really good codebase
 
+  it 'should return EXIT_STATUS_SUCCESS when no suggestions' do
+    Dir.chdir fixture_path(:ruby, :really_good)
+    _out, _err = capture_io do
+      assert_equal @command.run.exit_status, @command::EXIT_STATUS_SUCCESS
+    end
+  end
+
   it 'should run without args on really good fixture' do
     out, err = capture_io do
       Dir.chdir fixture_path(:ruby, :really_good)

data/test/unit/language/javascript/code_object/function_object_test.rb

@@ -1,6 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../../../test_helper')
 
-describe ::Inch::Language::Elixir::CodeObject::FunctionObject do
+describe ::Inch::Language::JavaScript::CodeObject::FunctionObject do
   before do
     @codebase = fresh_codebase(:javascript, :inch_test, 'all.json')
     @objects = @codebase.objects
@@ -56,4 +56,17 @@ describe ::Inch::Language::Elixir::CodeObject::FunctionObject do
     assert m.has_code_example?
     assert m.has_multiple_code_examples?
   end
+
+  it 'should recognize nodoc' do
+    m = @objects.find('InchTest.Docs.Formatter.nodoc_ignore')
+    assert m.nodoc?
+
+    m = @objects.find('InchTest.Docs.Formatter.nodoc_istanbul')
+    assert m.nodoc?
+  end
+
+  it 'should recognize @also' do
+    list = @objects.to_a.map(&:fullname)
+    assert list.size == list.uniq.size, "There should be no duplicate fullnames."
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inch
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.7.0
 platform: ruby
 authors:
 - René Föhring
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-06 00:00:00.000000000 Z
+date: 2015-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler