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

at-tag main properties must now be on single line. 

Only the comment may span several lines.

This means we can just say:

  /**
   * @cfg
   * True to enable this component.
   */
  enabled: false,

Previously this meant that we declared cfg with name "True",
but now the name cannot come after newline, so we can leave the
name out of the doc-comment and infer it from the source.

Parser enhancements to be able to infer @cfg and @event name from code.

DocComment enhancements to be able to set the name of at-tags other than
the default.
parent 88dd2f42

doc_comment.rb

+8 −0
Original line number Diff line number Diff line
@@ -20,6 +20,14 @@ module JsDuck 
      if !@tags[:class] && !@tags[:function] && !@tags[:event] && !@tags[:cfg] then

        @tags[tagname] = {:name => (tagname == :function) ? name : name_chain.join(".")}

        @tags[tagname][:doc] = @tags[:default][:doc]

      elsif @tags[:class] && !@tags[:class][:name] then

        @tags[:class][:name] = name

      elsif @tags[:function] && !@tags[:function][:name] then

        @tags[:function][:name] = name

      elsif @tags[:event] && !@tags[:event][:name] then

        @tags[:event][:name] = name

      elsif @tags[:cfg] && !@tags[:cfg][:name] then

        @tags[:cfg][:name] = name

      end

    end

doc_comment_parser.rb

+14 −9
Original line number Diff line number Diff line
@@ -84,7 +84,7 @@ module JsDuck 
    def at_class

      match(/@class/)

      set_root_tag(:class, {:doc => ""})

      skip_white

      skip_horiz_white

      if look(/\w/) then

        @current_tag[:name] = ident_chain

      end
@@ -98,7 +98,7 @@ module JsDuck 
        @tags[:class] = {:doc => ""}

      end

      @current_tag = @tags[:class]

      skip_white

      skip_horiz_white

      if look(/\w/) then

        @current_tag[:extends] = ident_chain

      end
@@ -109,7 +109,7 @@ module JsDuck 
    def at_event

      match(/@event/)

      set_root_tag(:event, {:doc => ""})

      skip_white

      skip_horiz_white

      if look(/\w/) then

        @current_tag[:name] = ident

      end
@@ -120,7 +120,7 @@ module JsDuck 
    def at_function

      match(/@function/)

      set_root_tag(:function, {:doc => ""})

      skip_white

      skip_horiz_white

      if look(/\w/) then

        @current_tag[:name] = ident

      end
@@ -144,11 +144,11 @@ module JsDuck 
      else

        @tags[:param] = [@current_tag]

      end

      skip_white

      skip_horiz_white

      if look(/\{/) then

        @current_tag[:type] = typedef

      end

      skip_white

      skip_horiz_white

      if look(/\w/) then

        @current_tag[:name] = ident

      end
@@ -159,7 +159,7 @@ module JsDuck 
    def at_return

      match(/@return/)

      @current_tag = @tags[:return] = {:doc => ""}

      skip_white

      skip_horiz_white

      if look(/\{/) then

        @current_tag[:type] = typedef

      end
@@ -170,11 +170,11 @@ module JsDuck 
    def at_cfg

      match(/@cfg/)

      set_root_tag(:cfg, {:doc => ""})

      skip_white

      skip_horiz_white

      if look(/\{/) then

        @current_tag[:type] = typedef

      end

      skip_white

      skip_horiz_white

      if look(/\w/) then

        @current_tag[:name] = ident

      end
@@ -210,6 +210,11 @@ module JsDuck 
    def skip_white

      @input.scan(/\s+/)

    end



    # skips horizontal whitespace (tabs and spaces)

    def skip_horiz_white

      @input.scan(/[ \t]+/)

    end

  end



end

parser.rb

+3 −1
Original line number Diff line number Diff line
@@ -56,6 +56,8 @@ module JsDuck 
        property_literal

      elsif look(:ident) then

        maybe_assignment

      elsif look(:string) then

        {:type => :assignment, :left => [match(:string)]}

      else

        {:type => :nop}

      end
@@ -143,7 +145,7 @@ module JsDuck 
      right = expression

      return {

        :type => :assignment,

        :left => left,

        :left => [left],

        :right => right,

      }

    end

tc_doc_comment_parser.rb

+45 −0
Original line number Diff line number Diff line
@@ -103,5 +103,50 @@ class TestDocCommentParser < Test::Unit::TestCase 
    assert_equal(nil, doc[:param][0][:type])

    assert_equal(nil, doc[:return][:type])

  end



  def test_nameless_function

    doc = parse_single("/**

 * @function

 * Comment for this func.

 */")

    assert_equal(nil, doc[:function][:name])

    assert_equal("Comment for this func.", doc[:function][:doc])

  end



  def test_nameless_class

    doc = parse_single("/**

 * @class

 * Comment for this class.

 */")

    assert_equal(nil, doc[:class][:name])

    assert_equal("Comment for this class.", doc[:class][:doc])

  end



  def test_nameless_event

    doc = parse_single("/**

 * @event

 * Comment for event.

 */")

    assert_equal(nil, doc[:event][:name])

    assert_equal("Comment for event.", doc[:event][:doc])

  end



  def test_nameless_cfg

    doc = parse_single("/**

 * @cfg

 * Config comment.

 */")

    assert_equal(nil, doc[:cfg][:name])

    assert_equal("Config comment.", doc[:cfg][:doc])

  end



  def test_nameless_param

    doc = parse_single("/**

 * @param

 * My parameter.

 */")

    assert_equal(nil, doc[:param][0][:name])

    assert_equal("My parameter.", doc[:param][0][:doc])

  end

end