Add --hide-api option

Hides any objects tagged with a given @api tag from documentation.

Closes #685

lib/yard/cli/yardoc.rb

@@ -175,6 +175,11 @@ class Yardoc < YardoptsCommand
       # @since 0.8.1
       attr_accessor :apis
 
+      # Keep track of which APIs are to be hidden
+      # @return [Array<String>] a list of APIs to be hidden
+      # @since 0.8.6.3
+      attr_accessor :hidden_apis
+
       # @return [Array<Symbol>] a list of tags to hide from templates
       # @since 0.6.0
       attr_accessor :hidden_tags
@@ -198,6 +203,7 @@ def initialize
         @options.reset_defaults
         @visibilities = [:public]
         @apis = []
+        @hidden_apis = []
         @assets = {}
         @excluded = []
         @files = []
@@ -430,11 +436,22 @@ def add_visibility_verifier
       # @return [void]
       # @since 0.8.1
       def add_api_verifier
-        return if apis.empty?
         no_api = true if apis.delete('')
-        expr = "#{apis.uniq.inspect}.include?(@api.text)"
-        expr += " || !@api" if no_api
-        options.verifier.add_expressions(expr)
+        exprs = []
+
+        if apis.size > 0
+          exprs << "#{apis.uniq.inspect}.include?(@api.text)"
+        end
+
+        if hidden_apis.size > 0
+          exprs << "!#{hidden_apis.uniq.inspect}.include?(@api.text)"
+        end
+
+        exprs = exprs.size > 0 ? [exprs.join(' && ')] : []
+        exprs << "!@api" if no_api
+
+        expr = exprs.join(' || ')
+        options.verifier.add_expressions(expr) unless expr.empty?
       end
 
       # Applies the specified locale to collected objects
@@ -566,6 +583,10 @@ def output_options(opts)
           apis.push(api)
         end
 
+        opts.on('--hide-api API', 'Hides given @api tag from documentation') do |api|
+          hidden_apis.push(api)
+        end
+
         opts.on('--embed-mixins', "Embeds mixin methods into class documentation") do
           options.embed_mixins << '*'
         end

spec/cli/yardoc_spec.rb

@@ -400,6 +400,33 @@ class Baz; end
     end
   end
 
+  describe '--hide-api option' do
+    it "should allow --hide-api to hide objects with api tags" do
+      YARD.parse_string <<-eof
+        # @api private
+        class Foo; end
+        class Bar; end
+        class Baz; end
+      eof
+      @yardoc.run('--hide-api', 'private')
+      @yardoc.options.verifier.run(Registry.all).
+        sort_by {|o| o.path }.should == [P('Bar'), P('Baz')]
+    end
+
+    it "should allow --hide-api to work with --api" do
+      YARD.parse_string <<-eof
+        # @api private
+        class Foo; end
+        # @api public
+        class Bar; end
+        class Baz; end
+      eof
+      @yardoc.run('--api', 'public', '--hide-api', 'private')
+      @yardoc.options.verifier.run(Registry.all).
+        sort_by {|o| o.path }.should == [P('Bar')]
+    end
+  end
+
   describe '--no-private option' do
     it "should accept --no-private" do
       obj = mock(:object)