Commit afaf889e authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

New syntax for optional parameters. 

Now supporting both:

    @param {Type} foo (optional)
    @param {Type} [foo]
parent 665ac3cb

lib/jsduck/doc_parser.rb

+20 −2
Original line number Diff line number Diff line
@@ -184,12 +184,30 @@ module JsDuck 
      skip_white

    end



    # matches @param {type} name ...

    # matches @param {type} [name] (optional) ...

    def at_param

      match(/@param/)

      add_tag(:param)

      maybe_type

      skip_horiz_white



      if look(/\[/)

        match(/\[/)

        maybe_ident_chain(:name)

        skip_horiz_white

        if look(/\]/)

          match(/\]/)

          @current_tag[:optional] = true

        end

      else

        maybe_ident_chain(:name)

      end



      skip_horiz_white

      if look(/\(optional\)/i)

        match(/\(optional\)/i)

        @current_tag[:optional] = true

      end

      skip_white

    end

lib/jsduck/merger.rb

+1 −2
Original line number Diff line number Diff line
@@ -318,8 +318,7 @@ module JsDuck 
          :type => ex[:type] || im[:type] || "Object",

          :name => ex[:name] || im[:name] || "",

          :doc => doc,

          # convert to boolean for JavaScript export, otherwise it's 0 or nil

          :optional => !!(doc =~ /\(optional\)/i),

          :optional => ex[:optional] || false,

          :properties => ex[:properties] || [],

        }

      end

spec/aggregator_default_values_spec.rb

0 → 100644
+90 −0
Original line number Diff line number Diff line 
require "jsduck/aggregator"

require "jsduck/source_file"



describe JsDuck::Aggregator do



  def parse(string)

    agr = JsDuck::Aggregator.new

    agr.aggregate(JsDuck::SourceFile.new(string))

    agr.result

  end



  shared_examples_for "optional parameter" do

    it "makes parameter optional" do

      @param[:optional].should == true

    end



    it "keeps parameter name" do

      @param[:name].should == "foo"

    end



    it "leaves optionality syntax out of description" do

      @param[:doc].should == "Something"

    end

  end



  describe "parameter name followed with (optional)" do

    before do

      @param = parse(<<-EOS)[0][:params][0]

        /**

         * @param {Number} foo (optional) Something

         */

        function foo() {

      EOS

    end

    it_should_behave_like "optional parameter"

  end



  describe "parameter name followed with mixed-case (Optional)" do

    before do

      @param = parse(<<-EOS)[0][:params][0]

        /**

         * @param {Number} foo (Optional) Something

         */

        function foo() {

      EOS

    end

    it_should_behave_like "optional parameter"

  end



  describe "parameter name followed with 'optional'" do

    before do

      @param = parse(<<-EOS)[0][:params][0]

        /**

         * @param {Number} foo optional Something

         */

        function foo() {

      EOS

    end

    it "doesn't make parameter optional" do

      @param[:optional].should == false

    end

  end



  describe "parameter description containing (optional)" do

    before do

      @param = parse(<<-EOS)[0][:params][0]

        /**

         * @param {Number} foo Something (optional)

         */

        function foo() {

      EOS

    end

    it "doesn't make parameter optional" do

      @param[:optional].should == false

    end

  end



  describe "parameter name in [brackets]" do

    before do

      @param = parse(<<-EOS)[0][:params][0]

        /**

         * @param {Number} [foo] Something

         */

        function foo() {

      EOS

    end

    it_should_behave_like "optional parameter"

  end



end

spec/aggregator_methods_and_events_spec.rb

+0 −31
Original line number Diff line number Diff line
@@ -236,37 +236,6 @@ describe JsDuck::Aggregator do 
    it_should_behave_like "parameter types"

  end



  describe "method with optional parameters" do

    before do

      @doc = parse(<<-EOS)[0]

        /**

         * Some function

         * @param {String} x (optional) my comment 1

         * @param {Number} y (Optional) my comment 2

         * @param {Number} y my comment 3 (optional)

         * @param {Number} z optional my comment 4

         */

        function foo(x, y) {}

      EOS

    end



    it "recognizes (optional) at the beginning of comment" do

      @doc[:params][0][:optional].should == true

    end



    it "recognizes mixed case (Optional) at the beginning of comment" do

      @doc[:params][1][:optional].should == true

    end



    it "recognizes (optional) anywhere inside comment" do

      @doc[:params][2][:optional].should == true

    end



    it "doesn't recognize 'optional' without parens" do

      @doc[:params][3][:optional].should == false

    end

  end



  describe "@return documenting return value" do

    before do

      @doc = parse(<<-EOS)[0]