Add support for an "include" option

 * Added support for -i or -include which has the opposite behavior of the exclude flag
 * Updated file filtering to account for include flag
 * Updated README and documentation

CHANGELOG.md

@@ -6,7 +6,10 @@
 
 ##### Enhancements
 
-* None.
+* Added the ability to limit documentation to certain files by passing in an
+  `-i`/`--include` argument.  
+  [Nick Fox](https://github.com/nicholasffox)
+  [#949](https://github.com/realm/jazzy/issues/949)
 
 ##### Bug Fixes
 

README.md

@@ -197,21 +197,28 @@ include declarations with a lower access level, set the `--min-acl` flag to `int
 In Objective-C mode, Jazzy documents all declarations found in the `--umbrella-header`
 header file and any other header files included by it.
 
-You can then prevent some of these declarations from being documented using `--exclude`
-or `:nodoc:`.
-
-The `--exclude` flag lists source files to omit from the documentation. Entries in the
-list can be absolute pathnames beginning with `/` or relative pathnames. Relative
-pathnames are interpreted relative to the directory from where you run `jazzy` or, if the
-exclude flag is set in the config file, relative to the directory containing the config
-file. Entries in the list can match multiple files using `*` to match any number of
-characters including `/`.  For example:
-* `jazzy --exclude=/Users/fred/project/Sources/Secret.swift` -- exclude a specific file
+You can control exactly which declarations should be documented using `--exclude`,
+`--include`, or `:nodoc:`.
+
+The `--include` and `--exclude` flags list source files that should be included/excluded
+respectively in the documentation. Entries in the list can be absolute pathnames beginning
+with `/` or relative pathnames. Relative pathnames are interpreted relative to the
+directory from where you run `jazzy` or, if the flags are set in the config file, relative
+to the directory containing the config file. Entries in the list can match multiple files
+using `*` to match any number of characters including `/`.  For example:
+* `jazzy --include=/Users/fred/project/Sources/Secret.swift` -- include a specific file
 * `jazzy --exclude=/*/Internal*` -- exclude all files with names that begin with *Internal*
   and any files under any directory with a name beginning *Internal*.
 * `jazzy --exclude=Impl1/*,Impl2/*` -- exclude all files under the directories *Impl1* and
   *Impl2* found in the current directory.
 
+Note that the `--include` option is applied before the `--exclude` option. For example:
+
+* `jazzy --include=/*/Internal* --exclude=Impl1/*,Impl2/*` -- include all files with names
+  that begin with *Internal* and any files under any directory with a name beginning
+  *Internal*, **except** for those under the directories *Impl1* and *Impl2* found in the
+  current directory
+
 Declarations with a documentation comment containing `:nodoc:` are excluded from the
 documentation.
 

lib/jazzy/config.rb

@@ -167,6 +167,15 @@ def expand_path(path)
         Array(files).map { |f| expand_path(f).to_s }
       end
 
+    config_attr :included_files,
+      command_line: ['-i', '--include filepath1,filepath2,…filepathN', Array],
+      description: 'Source file pathnames to be included in documentation. '\
+                   'Supports wildcards.',
+      default: [],
+      parse: ->(files) do
+        Array(files).map { |f| expand_path(f).to_s }
+      end
+
     config_attr :swift_version,
       command_line: '--swift-version VERSION',
       default: nil,

lib/jazzy/sourcekitten.rb

@@ -538,11 +538,33 @@ def self.mark_members_from_protocol_extension(extensions)
       end
     end
 
+    # Apply filtering based on the "included" and "excluded" flags.
+    def self.filter_files(json)
+      json = filter_included_files(json) if Config.instance.included_files.any?
+      json = filter_excluded_files(json) if Config.instance.excluded_files.any?
+      json.map do |doc|
+        key = doc.keys.first
+        doc[key]
+      end.compact
+    end
+
+    # Filter based on the "included" flag.
+    def self.filter_included_files(json)
+      included_files = Config.instance.included_files
+      json.map do |doc|
+        key = doc.keys.first
+        doc if included_files.detect do |include|
+          File.fnmatch?(include, key)
+        end
+      end.compact
+    end
+
+    # Filter based on the "excluded" flag.
     def self.filter_excluded_files(json)
       excluded_files = Config.instance.excluded_files
       json.map do |doc|
         key = doc.keys.first
-        doc[key] unless excluded_files.detect do |exclude|
+        doc unless excluded_files.detect do |exclude|
           File.fnmatch?(exclude, key)
         end
       end.compact
@@ -665,7 +687,7 @@ def self.parse(sourcekitten_output, min_acl, skip_undocumented, inject_docs)
       @min_acl = min_acl
       @skip_undocumented = skip_undocumented
       @stats = Stats.new
-      sourcekitten_json = filter_excluded_files(JSON.parse(sourcekitten_output))
+      sourcekitten_json = filter_files(JSON.parse(sourcekitten_output))
       docs = make_source_declarations(sourcekitten_json).concat inject_docs
       docs = expand_extensions(docs)
       docs = deduplicate_declarations(docs)