Declare --stdin with FILE argument for better help text

Before this change it is not apparent from the help text
that -s/--stdin takes a file name argument.

CHANGELOG.md

@@ -19,6 +19,7 @@
 * [#4218](https://github.com/bbatsov/rubocop/pull/4218): Make `Lint/NestedMethodDefinition` aware of class shovel scope. ([@drenmi][])
 * [#4198](https://github.com/bbatsov/rubocop/pull/4198): Make `Lint/AmbguousBlockAssociation` aware of operator methods. ([@drenmi][])
 * [#4152](https://github.com/bbatsov/rubocop/pull/4152): Make `Style/MethodCallWithArgsParentheses` not require parens on setter methods. ([@drenmi][])
+* [#4226](https://github.com/bbatsov/rubocop/pull/4226): Show in `--help` output that `--stdin` takes a file name argument. ([@jonas054][])
 
 ## 0.48.0 (2017-03-26)
 

lib/rubocop/options.rb

@@ -23,8 +23,16 @@ def parse(command_line_args)
 
       @validator.validate_compatibility
 
-      if @options[:stdin] && !args.one?
-        raise ArgumentError, '-s/--stdin requires exactly one path.'
+      if @options[:stdin]
+        # The parser has put the file name given after --stdin into
+        # @options[:stdin]. The args array should be empty.
+        if args.any?
+          raise ArgumentError, '-s/--stdin requires exactly one path.'
+        end
+        # We want the STDIN contents in @options[:stdin] and the file name in
+        # args to simplify the rest of the processing.
+        args = [@options[:stdin]]
+        @options[:stdin] = $stdin.binmode.read
       end
 
       [@options, args]
@@ -58,6 +66,8 @@ def define_options(args)
         add_severity_option(opts)
         add_flags_with_optional_args(opts)
         add_boolean_flags(opts)
+
+        option(opts, '-s', '--stdin FILE')
       end
     end
 
@@ -146,7 +156,6 @@ def add_boolean_flags(opts) # rubocop:disable Metrics/MethodLength
 
       option(opts, '-v', '--version')
       option(opts, '-V', '--verbose-version')
-      option(opts, '-s', '--stdin') { @options[:stdin] = $stdin.binmode.read }
     end
 
     def add_list_options(opts)
@@ -314,8 +323,8 @@ module OptionsHelp
       no_color:              'Force color output on or off.',
       version:               'Display version.',
       verbose_version:       'Display verbose version.',
-      stdin:                ['Pipe source from STDIN.',
-                             'This is useful for editor integration.']
+      stdin:                ['Pipe source from STDIN, using FILE in offense',
+                             'reports. This is useful for editor integration.']
     }.freeze
   end
 end

spec/rubocop/cli/cli_options_spec.rb

@@ -1061,9 +1061,7 @@ def finished(processed_files)
                   '--format=simple',
                   '--stdin']
         expect(cli.run(argv)).to eq(2)
-        expect($stderr.string).to include(
-          '-s/--stdin requires exactly one path.'
-        )
+        expect($stderr.string).to include('missing argument: --stdin')
       ensure
         $stdin = STDIN
       end

spec/rubocop/options_spec.rb

@@ -93,8 +93,8 @@ def abs(path)
                   --[no-]color                 Force color output on or off.
               -v, --version                    Display version.
               -V, --verbose-version            Display verbose version.
-              -s, --stdin                      Pipe source from STDIN.
-                                               This is useful for editor integration.
+              -s, --stdin FILE                 Pipe source from STDIN, using FILE in offense
+                                               reports. This is useful for editor integration.
         END
 
         expect($stdout.string).to eq(expected_help)
@@ -247,7 +247,8 @@ def abs(path)
       end
 
       it 'fails if no paths are given' do
-        expect { options.parse %w(-s) }.to raise_error(ArgumentError)
+        expect { options.parse %w(-s) }
+          .to raise_error(OptionParser::MissingArgument)
       end
 
       it 'succeeds with exactly one path' do