Auto merge of #4343 - sonalkr132:doc-lang-quality, r=segiddins

Add test for checking quality of documentation

close #4338

Sample run:

```
1) The library itself maitains language quality of the documentation
     Failure/Error: expect(error_messages.compact).to be_well_formed

       bundle-install.ronn has 'actually' on line 210. Avoid using such words.
       bundle-install.ronn has 'just' on line 269. Avoid using such words.
       bundle-package.ronn has 'actually' on line 46. Avoid using such words.
       ...
```

cc: @RochesterinNYC

24 files changed, 86 insertions, 36 deletions

diff --git a/lib/bundler.rb b/lib/bundler.rb
index dcb151b058..8288f839e1 100644
--- a/lib/bundler.rb
+++ b/lib/bundler.rb
@@ -85,7 +85,7 @@ module Bundler
     end
 
     def setup(*groups)
-      # Just return if all groups are already loaded
+      # Return if all groups are already loaded
       return @setup if defined?(@setup)
 
       definition.validate_ruby!
diff --git a/lib/bundler/capistrano.rb b/lib/bundler/capistrano.rb
index 2a4954d964..7b0bbbd6d2 100644
--- a/lib/bundler/capistrano.rb
+++ b/lib/bundler/capistrano.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 # Capistrano task for Bundler.
 #
-# Just add "require 'bundler/capistrano'" in your Capistrano deploy.rb, and
+# Add "require 'bundler/capistrano'" in your Capistrano deploy.rb, and
 # Bundler will be activated after each new deployment.
 require "bundler/deployment"
 require "capistrano/version"
diff --git a/lib/bundler/cli.rb b/lib/bundler/cli.rb
index 82ca1cdb26..9834277cd8 100644
--- a/lib/bundler/cli.rb
+++ b/lib/bundler/cli.rb
@@ -259,7 +259,7 @@ module Bundler
 
     desc "cache [OPTIONS]", "Cache all the gems to vendor/cache", :hide => true
     method_option "all",  :type => :boolean, :banner => "Include all sources (including path and git)."
-    method_option "all-platforms", :type => :boolean, :banner => "Include gems for all platforms present in the lockfile, not just the current one"
+    method_option "all-platforms", :type => :boolean, :banner => "Include gems for all platforms present in the lockfile, not only the current one"
     method_option "no-prune", :type => :boolean, :banner => "Don't remove stale gems from the cache."
     def cache
       require "bundler/cli/cache"
@@ -268,11 +268,11 @@ module Bundler
 
     desc "package [OPTIONS]", "Locks and then caches all of the gems into vendor/cache"
     method_option "all",  :type => :boolean, :banner => "Include all sources (including path and git)."
-    method_option "all-platforms", :type => :boolean, :banner => "Include gems for all platforms present in the lockfile, not just the current one"
+    method_option "all-platforms", :type => :boolean, :banner => "Include gems for all platforms present in the lockfile, not only the current one"
     method_option "cache-path", :type => :string, :banner =>
       "Specify a different cache path than the default (vendor/cache)."
     method_option "gemfile", :type => :string, :banner => "Use the specified gemfile instead of Gemfile"
-    method_option "no-install", :type => :boolean, :banner => "Don't actually install the gems, just package."
+    method_option "no-install", :type => :boolean, :banner => "Don't install the gems, only the package."
     method_option "no-prune", :type => :boolean, :banner => "Don't remove stale gems from the cache."
     method_option "path", :type => :string, :banner =>
       "Specify a different path than the system default ($BUNDLE_PATH or $GEM_HOME). Bundler will remember this value for future installs on this machine"
@@ -390,7 +390,7 @@ module Bundler
 
     desc "clean [OPTIONS]", "Cleans up unused gems in your bundler directory"
     method_option "dry-run", :type => :boolean, :default => false, :banner =>
-      "Only print out changes, do not actually clean gems"
+      "Only print out changes, do not clean gems"
     method_option "force", :type => :boolean, :default => false, :banner =>
       "Forces clean even if --path is not set"
     def clean
diff --git a/lib/bundler/cli/exec.rb b/lib/bundler/cli/exec.rb
index 9162d54913..3ef2492c2f 100644
--- a/lib/bundler/cli/exec.rb
+++ b/lib/bundler/cli/exec.rb
@@ -25,7 +25,7 @@ module Bundler
         # First, try to exec directly to something in PATH
         kernel_exec([bin_path, cmd], *args)
       else
-        # Just exec using the given command
+        # exec using the given command
         kernel_exec(cmd, *args)
       end
     end
diff --git a/lib/bundler/cli/install.rb b/lib/bundler/cli/install.rb
index 8f27f7cfcc..da201ec5d9 100644
--- a/lib/bundler/cli/install.rb
+++ b/lib/bundler/cli/install.rb
@@ -42,7 +42,7 @@ module Bundler
 
       ENV["RB_USER_INSTALL"] = "1" if Bundler::FREEBSD
 
-      # Just disable color in deployment mode
+      # Disable color in deployment mode
       Bundler.ui.shell = Thor::Shell::Basic.new if options[:deployment]
 
       check_for_options_conflicts
diff --git a/lib/bundler/cli/update.rb b/lib/bundler/cli/update.rb
index 1a76a88c3d..037da2915e 100644
--- a/lib/bundler/cli/update.rb
+++ b/lib/bundler/cli/update.rb
@@ -21,7 +21,7 @@ module Bundler
           raise GemfileLockNotFound, "This Bundle hasn't been installed yet. " \
             "Run `bundle install` to update and install the bundled gems."
         end
-        # cycle through the requested gems, just to make sure they exist
+        # cycle through the requested gems, to make sure they exist
         names = Bundler.locked_gems.specs.map(&:name)
         gems.each do |g|
           next if names.include?(g)
diff --git a/lib/bundler/definition.rb b/lib/bundler/definition.rb
index 944b8089c1..3dcac64191 100644
--- a/lib/bundler/definition.rb
+++ b/lib/bundler/definition.rb
@@ -572,7 +572,7 @@ module Bundler
         next if s.source.nil? || @unlock[:sources].include?(s.name)
 
         # If the spec is from a path source and it doesn't exist anymore
-        # then we just unlock it.
+        # then we unlock it.
 
         # Path sources have special logic
         if s.source.instance_of?(Source::Path)
diff --git a/lib/bundler/dsl.rb b/lib/bundler/dsl.rb
index b3b6bfdcce..224e642bd4 100644
--- a/lib/bundler/dsl.rb
+++ b/lib/bundler/dsl.rb
@@ -103,7 +103,7 @@ module Bundler
         else
           Bundler.ui.warn "Your Gemfile lists the gem #{current.name} (#{current.requirement}) more than once.\n" \
                           "You should probably keep only one of them.\n" \
-                          "While it's not a problem now, it could cause errors if you change the version of just one of them later."
+                          "While it's not a problem now, it could cause errors if you change the version of one of them later."
         end
 
         if current.source != dep.source
diff --git a/lib/bundler/fetcher/compact_index.rb b/lib/bundler/fetcher/compact_index.rb
index f249ec1835..c1beee6c75 100644
--- a/lib/bundler/fetcher/compact_index.rb
+++ b/lib/bundler/fetcher/compact_index.rb
@@ -16,7 +16,7 @@ module Bundler
           rescue NetworkDownError, CompactIndexClient::Updater::MisMatchedChecksumError => e
             raise HTTPError, e.message
           rescue AuthenticationRequiredError
-            # We got a 401 from the server. Just fail.
+            # Fail since we got a 401 from the server.
             raise
           rescue HTTPError => e
             Bundler.ui.trace(e)
diff --git a/lib/bundler/fetcher/dependency.rb b/lib/bundler/fetcher/dependency.rb
index 274b34eefd..8b41fe9999 100644
--- a/lib/bundler/fetcher/dependency.rb
+++ b/lib/bundler/fetcher/dependency.rb
@@ -10,7 +10,7 @@ module Bundler
       rescue NetworkDownError => e
         raise HTTPError, e.message
       rescue AuthenticationRequiredError
-        # We got a 401 from the server. Just fail.
+        # Fail since we got a 401 from the server.
         raise
       rescue HTTPError
         false
diff --git a/lib/bundler/friendly_errors.rb b/lib/bundler/friendly_errors.rb
index b453e8e625..f7a10d0035 100644
--- a/lib/bundler/friendly_errors.rb
+++ b/lib/bundler/friendly_errors.rb
@@ -63,7 +63,7 @@ module Bundler
 
         - What happened instead?
 
-          Instead, what actually happened was...
+          Instead, what happened was...
 
 
         Error details
diff --git a/lib/bundler/installer.rb b/lib/bundler/installer.rb
index 10ba3005d1..509b7b0cba 100644
--- a/lib/bundler/installer.rb
+++ b/lib/bundler/installer.rb
@@ -146,9 +146,9 @@ module Bundler
   private
 
     # the order that the resolver provides is significant, since
-    # dependencies might actually affect the installation of a gem.
+    # dependencies might affect the installation of a gem.
     # that said, it's a rare situation (other than rake), and parallel
-    # installation is just SO MUCH FASTER. so we let people opt in.
+    # installation is SO MUCH FASTER. so we let people opt in.
     def install(options)
       force = options["force"]
       jobs = 1
diff --git a/lib/bundler/installer/gem_installer.rb b/lib/bundler/installer/gem_installer.rb
index 441c72108f..a91990d5f5 100644
--- a/lib/bundler/installer/gem_installer.rb
+++ b/lib/bundler/installer/gem_installer.rb
@@ -39,7 +39,7 @@ module Bundler
     end
 
     def handle_exception(e)
-      # if install hook failed or gem signature is bad, just die
+      # Die if install hook failed or gem signature is bad.
       raise e if e.is_a?(Bundler::InstallHookError) || e.is_a?(Bundler::SecurityError)
       # other failure, likely a native extension build failure
       Bundler.ui.info ""
diff --git a/lib/bundler/mirror.rb b/lib/bundler/mirror.rb
index 4978462bb3..cc427d7314 100644
--- a/lib/bundler/mirror.rb
+++ b/lib/bundler/mirror.rb
@@ -177,7 +177,7 @@ module Bundler
   #   a given mirror.
   #
   # One mirror may correspond to many different addresses, both
-  #   because of it having many dns entries or just because
+  #   because of it having many dns entries or because
   #   the network interface is both ipv4 and ipv5
   class MirrorSockets
     def initialize(mirror)
diff --git a/lib/bundler/psyched_yaml.rb b/lib/bundler/psyched_yaml.rb
index 2c85cb0a53..69d2ae78c5 100644
--- a/lib/bundler/psyched_yaml.rb
+++ b/lib/bundler/psyched_yaml.rb
@@ -5,7 +5,7 @@ begin
 rescue LoadError
 end if defined?(gem)
 
-# Psych could just be in the stdlib
+# Psych could be in the stdlib
 # but it's too late if Syck is already loaded
 begin
   require "psych" unless defined?(Syck)
diff --git a/lib/bundler/source/git.rb b/lib/bundler/source/git.rb
index 228ab61a67..7926a7b50a 100644
--- a/lib/bundler/source/git.rb
+++ b/lib/bundler/source/git.rb
@@ -146,7 +146,7 @@ module Bundler
         changed
       end
 
-      # TODO: actually cache git specs
+      # TODO: cache git specs
       def specs(*)
         set_local!(app_cache_path) if has_app_cache? && !local?
 
diff --git a/lib/bundler/source/rubygems.rb b/lib/bundler/source/rubygems.rb
index cebb68a700..d8ca36e3f9 100644
--- a/lib/bundler/source/rubygems.rb
+++ b/lib/bundler/source/rubygems.rb
@@ -343,7 +343,7 @@ module Bundler
 
           # because ensuring we have all the gems we need involves downloading
           # the gemspecs of those gems, if the non-api sites contain more than
-          # about 100 gems, we just treat all sites as non-api for speed.
+          # about 100 gems, we treat all sites as non-api for speed.
           allow_api = idx.size < API_REQUEST_LIMIT && dependency_names.size < API_REQUEST_LIMIT
           Bundler.ui.debug "Need to query more than #{API_REQUEST_LIMIT} gems." \
             " Downloading full index instead..." unless allow_api
diff --git a/lib/bundler/vlad.rb b/lib/bundler/vlad.rb
index d017ca475a..db78f84baa 100644
--- a/lib/bundler/vlad.rb
+++ b/lib/bundler/vlad.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 # Vlad task for Bundler.
 #
-# Just add "require 'bundler/vlad'" in your Vlad deploy.rb, and
+# Add "require 'bundler/vlad'" in your Vlad deploy.rb, and
 # include the vlad:bundle:install task in your vlad:deploy task.
 require "bundler/deployment"
 
diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn
index b756ae2f7d..efbf06d136 100644
--- a/man/bundle-install.ronn
+++ b/man/bundle-install.ronn
@@ -207,7 +207,7 @@ other steps in `bundle install` must be performed as the current user:
 
 Of these three, the first two could theoretically be performed by
 `chown`ing the resulting files to `$SUDO_USER`. The third, however,
-can only be performed by actually invoking the `git` command as
+can only be performed by invoking the `git` command as
 the current user. Therefore, git gems are downloaded and installed
 into `~/.bundle` rather than $GEM_HOME or $BUNDLE_PATH.
 
@@ -266,7 +266,7 @@ This also means that you cannot include different versions of the same
 gem in different groups, because doing so would result in different
 sets of dependencies used in development and production. Because of
 the vagaries of the dependency resolution process, this usually
-affects more than just the gems you list in your Gemfile(5), and can
+affects more than the gems you list in your Gemfile(5), and can
 (surprisingly) radically change the gems you are using.
 
 ## REMEMBERED OPTIONS
diff --git a/man/bundle-package.ronn b/man/bundle-package.ronn
index efdfc125d6..eacb83b54d 100644
--- a/man/bundle-package.ronn
+++ b/man/bundle-package.ronn
@@ -44,12 +44,12 @@ to JRuby and run `bundle install`, bundler is forced to check to
 see whether a `"java"` platformed `nokogiri` exists.
 
 Even though the `nokogiri` gem for the Ruby platform is
-_technically_ acceptable on JRuby, it actually has a C extension
+_technically_ acceptable on JRuby, it has a C extension
 that does not run on JRuby. As a result, bundler will, by default,
 still connect to `rubygems.org` to check whether it has a version
 of one of your gems more specific to your platform.
 
-This problem is also not just limited to the `"java"` platform.
+This problem is also not limited to the `"java"` platform.
 A similar (common) problem can happen when developing on Windows
 and deploying to Linux, or even when developing on OSX and
 deploying to Linux.
@@ -57,7 +57,7 @@ deploying to Linux.
 If you know for sure that the gems packaged in `vendor/cache`
 are appropriate for the platform you are on, you can run
 `bundle install --local` to skip checking for more appropriate
-gems, and just use the ones in `vendor/cache`.
+gems, and use the ones in `vendor/cache`.
 
 One way to be sure that you have the right platformed versions
 of all your gems is to run `bundle package` on an identical
diff --git a/man/bundle-platform.ronn b/man/bundle-platform.ronn
index 922a9f1a09..b5d3283fb6 100644
--- a/man/bundle-platform.ronn
+++ b/man/bundle-platform.ronn
@@ -38,5 +38,5 @@ match the running Ruby VM, it will tell you what part does not.
 ## OPTIONS
 
 * `--ruby`:
-  It will just display the ruby directive information, so you don't have to
+  It will display the ruby directive information, so you don't have to
   parse it from the Gemfile(5).
diff --git a/man/bundle-update.ronn b/man/bundle-update.ronn
index b9900e3b50..d38c9d2f36 100644
--- a/man/bundle-update.ronn
+++ b/man/bundle-update.ronn
@@ -79,8 +79,8 @@ all of the dependencies, all the way down, and install what you need:
     Bundle complete! 2 Gemfile dependencies, 26 gems total.
     Use `bundle show [gemname]` to see where a bundled gem is installed.
 
-As you can see, even though you have just two gems in the Gemfile(5), your application
-actually needs 26 different gems in order to run. Bundler remembers the exact versions
+As you can see, even though you have two gems in the Gemfile(5), your application
+needs 26 different gems in order to run. Bundler remembers the exact versions
 it installed in `Gemfile.lock`. The next time you run [bundle install(1)][bundle-install], bundler skips
 the dependency resolution and installs the same gems as it installed last time.
 
diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn
index dc1a6b5acb..b707e2a5c5 100644
--- a/man/gemfile.5.ronn
+++ b/man/gemfile.5.ronn
@@ -137,10 +137,10 @@ The Bundler runtime allows its two main methods, `Bundler.setup` and
     Bundler.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others
 
     # require requires all of the gems in the specified groups
-    Bundler.require                  # defaults to just the _default_ group
+    Bundler.require                  # defaults to the _default_ group
     Bundler.require(:default)        # identical
     Bundler.require(:default, :test) # requires the _default_ and _test_ groups
-    Bundler.require(:test)           # requires just the _test_ group
+    Bundler.require(:test)           # requires the _test_ group
 
 The Bundler CLI allows you to specify a list of groups whose gems `bundle install` should
 not install with the `--without` option. To specify multiple groups to ignore, specify a
@@ -155,7 +155,7 @@ without any `--without option`, bundler will recall it.
 
 Also, calling `Bundler.setup` with no parameters, or calling `require "bundler/setup"`
 will setup all groups except for the ones you excluded via `--without` (since they
-are obviously not available).
+are not available).
 
 Note that on `bundle install`, bundler downloads and evaluates all gems, in order to
 create a single canonical list of all of the required gems and their dependencies.
@@ -353,7 +353,7 @@ currently expands to an insecure `git://` URL. This allows a
 man-in-the-middle attacker to compromise your system.
 
 If the git repository you want to use is hosted on GitHub and is public, you can use the
-:github shorthand to specify just the github username and repository name (without the
+:github shorthand to specify the github username and repository name (without the
 trailing ".git"), separated by a slash. If both the username and repository name are the
 same, you can omit one.
 
@@ -369,7 +369,7 @@ Since the `github` method is a specialization of `git_source`, it accepts a `:br
 ### GIST (:gist)
 
 If the git repository you want to use is hosted as a Github Gist and is public, you can use
-the :gist shorthand to specify just the gist identifier (without the trailing ".git").
+the :gist shorthand to specify the gist identifier (without the trailing ".git").
 
     gem "the_hatch", :gist => "4815162342"
 
@@ -382,7 +382,7 @@ Since the `gist` method is a specialization of `git_source`, it accepts a `:bran
 ### BITBUCKET (:bitbucket)
 
 If the git repository you want to use is hosted on Bitbucket and is public, you can use the
-:bitbucket shorthand to specify just the bitbucket username and repository name (without the
+:bitbucket shorthand to specify the bitbucket username and repository name (without the
 trailing ".git"), separated by a slash. If both the username and repository name are the
 same, you can omit one.
 
diff --git a/spec/quality_spec.rb b/spec/quality_spec.rb
index c68bfa1533..ce03839c17 100644
--- a/spec/quality_spec.rb
+++ b/spec/quality_spec.rb
@@ -40,6 +40,30 @@ describe "The library itself" do
     "#{filename} has spaces on the EOL on lines #{failing_lines.join(", ")}"
   end
 
+  def check_for_expendable_words(filename)
+    failing_line_message = []
+    useless_words = /\b(actually|obviously|just|clearly|basically|really)\b/i
+
+    File.readlines(filename).each_with_index do |line, number|
+      next unless word_found = useless_words.match(line)
+      failing_line_message << "#{filename} has '#{word_found}' on line #{number + 1}. Avoid using these kinds of weak modifiers."
+    end
+
+    failing_line_message unless failing_line_message.empty?
+  end
+
+  def check_for_specific_pronouns(filename)
+    failing_line_message = []
+    specific_pronouns = /\b(he|she|his|hers|him|her|himself|herself)\b/i
+
+    File.readlines(filename).each_with_index do |line, number|
+      next unless word_found = specific_pronouns.match(line)
+      failing_line_message << "#{filename} has '#{word_found}' on line #{number + 1}. Use more generic pronouns in documentation."
+    end
+
+    failing_line_message unless failing_line_message.empty?
+  end
+
   RSpec::Matchers.define :be_well_formed do
     match(&:empty?)
 
@@ -73,6 +97,32 @@ describe "The library itself" do
     expect(error_messages.compact).to be_well_formed
   end
 
+  it "maintains language quality of the documentation" do
+    included = /ronn/
+    error_messages = []
+    Dir.chdir(File.expand_path("../../man", __FILE__)) do
+      `git ls-files -z`.split("\x0").each do |filename|
+        next unless filename =~ included
+        error_messages << check_for_expendable_words(filename)
+        error_messages << check_for_specific_pronouns(filename)
+      end
+    end
+    expect(error_messages.compact).to be_well_formed
+  end
+
+  it "maintains language quality of sentences used in source code" do
+    error_messages = []
+    exempt = /vendor/
+    Dir.chdir(File.expand_path("../../lib", __FILE__)) do
+      `git ls-files -z`.split("\x0").each do |filename|
+        next if filename =~ exempt
+        error_messages << check_for_expendable_words(filename)
+        error_messages << check_for_specific_pronouns(filename)
+      end
+    end
+    expect(error_messages.compact).to be_well_formed
+  end
+
   it "can still be built" do
     Dir.chdir(root) do
       `gem build bundler.gemspec`