Commit 7e6171c2 authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Implement support for new @alias tag. 

Allows to avoid duplication of doc-comments when one class aliases
methods from other class.
parent 1acca4ee

lib/jsduck/aggregator.rb

+18 −0
Original line number Diff line number Diff line
@@ -7,6 +7,7 @@ module JsDuck 
      @documentation = []

      @classes = {}

      @orphans = []

      @aliases = []

      @current_class = nil

    end
@@ -80,6 +81,7 @@ module JsDuck 
      else

        add_orphan(node)

      end

      @aliases << node if node[:alias]

    end



    def add_orphan(node)
@@ -110,6 +112,22 @@ module JsDuck 
      end

    end



    # Copy over doc/params/return from original methods to aliases.

    # Aliases are currently only supported for methods.

    def populate_aliases

      @aliases.each do |al|

        orig = get_member(al[:alias][:cls], al[:alias][:member])

        al[:doc] = al[:doc] + "\n\n" + orig[:doc]

        al[:params] = orig[:params]

        al[:return] = orig[:return]

      end

    end



    def get_member(cls_name, member_name)

      cls = @classes[cls_name]

      return cls[:method].find {|m| m[:name] == member_name }

    end



    # Creates class with name "global" and inserts all the remaining

    # orphans into it (but only if there are any orphans).

    def create_global_class

lib/jsduck/app.rb

+1 −0
Original line number Diff line number Diff line
@@ -122,6 +122,7 @@ module JsDuck 
        agr.aggregate(file)

      end

      agr.classify_orphans

      agr.populate_aliases

      agr.create_global_class unless @ignore_global

      agr.result

    end

lib/jsduck/doc_parser.rb

+17 −0
Original line number Diff line number Diff line
@@ -101,6 +101,8 @@ module JsDuck 
          at_ftype

        elsif look(/@member\b/)

          at_member

        elsif look(/@alias\b/)

          at_alias

        elsif look(/@author\b/)

          at_author

        elsif look(/@docauthor\b/)
@@ -269,6 +271,21 @@ module JsDuck 
      skip_white

    end



    # matches @alias class.name#member

    def at_alias

      match(/@alias/)

      add_tag(:alias)

      skip_horiz_white

      if look(/\w/)

        @current_tag[:cls] = ident_chain

        if look(/#\w/)

          @input.scan(/#/)

          @current_tag[:member] = ident

        end

      end

      skip_white

    end



    # matches @author some name ... newline

    def at_author

      match(/@author/)

lib/jsduck/merger.rb

+1 −0
Original line number Diff line number Diff line
@@ -202,6 +202,7 @@ module JsDuck 
        :protected => !!doc_map[:protected],

        :static => !!doc_map[:static],

        :deprecated => detect_deprecated(doc_map),

        :alias => doc_map[:alias] ? doc_map[:alias].first : nil,

      })

    end

spec/aggregator_alias_spec.rb

0 → 100644
+60 −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.populate_aliases

    agr.result

  end



  describe "@alias in doc-comment" do

    before do

      @docs = parse(<<-EOF)

        /** @class Foo */

          /**

           * @method bar

           * Original comment.

           * @param arg1

           * @param arg2

           * @return {String}

           */



        /** @class Core */

          /**

           * @method foobar

           * Alias comment.

           * @alias Foo#bar

           */

      EOF

      @orig = @docs[0][:method][0]

      @alias = @docs[1][:method][0]

    end



    it "original method keeps its name" do

      @orig[:name].should == "bar"

    end



    describe "alias" do

      it "keeps its name" do

        @alias[:name].should == "foobar"

      end



      it "inherits parameters" do

        @alias[:params].length.should == 2

      end



      it "inherits return value" do

        @alias[:return][:type].should == "String"

      end



      it "merges comment from original and its own comment" do

        @alias[:doc].should == "Alias comment.\n\nOriginal comment."

      end

    end

  end



end