Commit 9c2cf01a authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Introduce @alias tag to define class aliases. 

At the same time keep allow @alias to be used as @inheritdoc.

This will be treated as class alias:

    @alias foo.bar

While '#' in alias will signify that it's inheritdoc definition:

    @alias foo.bar#baz
parent 85374db3

lib/jsduck/doc_parser.rb

+27 −10
Original line number Diff line number Diff line
@@ -120,8 +120,14 @@ module JsDuck 
          at_ftype

        elsif look(/@member\b/)

          at_member

        elsif look(/@(inherit[dD]oc|alias)\b/)

        elsif look(/@inherit[dD]oc\b/)

          at_inheritdoc

        elsif look(/@alias\s+[\w.]+#\w+/)

          # For backwards compatibility.

          # @alias tag was used as @inheritdoc before

          at_inheritdoc

        elsif look(/@alias/)

          at_alias

        elsif look(/@deprecated\b/)

          at_deprecated

        elsif look(/@var\b/)
@@ -302,27 +308,38 @@ module JsDuck 
      skip_white

    end



    # matches @member name ...

    def at_member

      match(/@member/)

      add_tag(:member)

      maybe_ident_chain(:member)

      skip_white

    end



    # matches @xtype name

    def at_xtype

      match(/@xtype/)

      add_tag(:xtype)

      maybe_ident_chain(:name)

      add_tag(:alias)

      skip_horiz_white

      @current_tag[:name] = "widget." + ident_chain

      skip_white

    end



    # matches @ftype name

    def at_ftype

      match(/@ftype/)

      add_tag(:ftype)

      maybe_ident_chain(:name)

      add_tag(:alias)

      skip_horiz_white

      @current_tag[:name] = "feature." + ident_chain

      skip_white

    end



    # matches @member name ...

    def at_member

      match(/@member/)

      add_tag(:member)

      maybe_ident_chain(:member)

    # matches @alias <ident-chain>

    def at_alias

      match(/@alias/)

      add_tag(:alias)

      skip_horiz_white

      @current_tag[:name] = ident_chain

      skip_white

    end

lib/jsduck/merger.rb

+24 −20
Original line number Diff line number Diff line
@@ -103,7 +103,7 @@ module JsDuck 
          end

        end



        if tag[:tagname] == :xtype

        if tag[:tagname] == :alias

          groups[:class] << tag

        elsif group_name == :cfg

          groups[:cfg].last << tag
@@ -331,30 +331,34 @@ module JsDuck 
    end



    def detect_aliases(doc_map, code)

      if doc_map[:xtype]

        {"widget" => doc_map[:xtype].map {|tag| tag[:name] } }

      if doc_map[:alias]

        build_aliases_hash(doc_map[:alias].map {|tag| tag[:name] })

      elsif code[:xtype] || code[:alias]

        aliases = {}

        (code[:xtype] || []).each do |a|

          if aliases["widget"]

            aliases["widget"] << a

        hash = {}

        build_aliases_hash(code[:xtype].map {|xtype| "widget."+xtype }, hash) if code[:xtype]

        build_aliases_hash(code[:alias], hash) if code[:alias]

        hash

      else

            aliases["widget"] = [a]

        {}

      end

    end

        (code[:alias] || []).each do |a|



    # Given array of full alias names like "foo.bar", "foo.baz"

    # build hash like {"foo" => ["bar", "baz"]}

    #

    # When hash given as second argument, then merges the aliases into

    # it instead of creating a new hash.

    def build_aliases_hash(aliases, hash={})

      aliases.each do |a|

        if a =~ /^([\w.]+)\.(\w+)$/

            if aliases[$1]

              aliases[$1] << $2

          if hash[$1]

            hash[$1] << $2

          else

              aliases[$1] = [$2]

            hash[$1] = [$2]

          end

        end

      end

        aliases

      else

        {}

      end

      hash

    end



    def detect_meta(doc_map)

spec/aggregator_aliases_spec.rb

+39 −0
Original line number Diff line number Diff line
@@ -21,6 +21,31 @@ describe JsDuck::Aggregator do 
    end

  end



  describe "class with @alias" do

    before do

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

        /**

         * @class MyClass

         * @alias widget.foo

         */

      EOS

    end

    it_should_behave_like "single alias"

  end



  describe "class with multiple @alias tags" do

    before do

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

        /**

         * @class MyClass

         * @alias widget.foo

         * @alias widget.bar

         */

      EOS

    end

    it_should_behave_like "multiple aliases"

  end



  describe "class with @xtype" do

    before do

      @doc = parse(<<-EOS)[0]
@@ -74,6 +99,20 @@ describe JsDuck::Aggregator do 
    it_should_behave_like "single alias"

  end



  describe "Ext.define() with @alias overriding alias" do

    before do

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

        /**

         * @alias widget.foo

         */

        Ext.define('MyClass', {

          alias: 'widget.xxx'

        });

      EOS

    end

    it_should_behave_like "single alias"

  end



  describe "Ext.define() with @xtype overriding alias" do

    before do

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

spec/aggregator_xtypes_spec.rb

deleted100644 → 0
+0 −173
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 "single xtype" do

    it "detects xtype" do

      @doc[:xtypes].should == {"widget" => ["foo"]}

    end

  end



  shared_examples_for "multiple xtypes" do

    it "collects all xtypes together" do

      @doc[:xtypes].should == {"widget" => ["foo", "bar"]}

    end

  end



  describe "class with @xtype" do

    before do

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

        /**

         * @class MyClass

         * @xtype foo

         */

      EOS

    end

    it_should_behave_like "single xtype"

  end



  describe "@xtype after @constructor" do

    before do

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

        /**

         * @class MyClass

         * Comment here.

         * @constructor

         * This constructs the class

         * @xtype foo

         */

      EOS

    end

    it_should_behave_like "single xtype"

  end



  describe "class with multiple @xtypes" do

    before do

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

        /**

         * @class MyClass

         * @xtype foo

         * @xtype bar

         * Some documentation.

         */

      EOS

    end

    it_should_behave_like "multiple xtypes"

  end



  describe "Ext.define() with simple alias" do

    before do

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

        /** */

        Ext.define('MyClass', {

          alias: 'widget.foo'

        });

      EOS

    end

    it_should_behave_like "single xtype"

  end



  describe "Ext.define() with @xtype overriding alias" do

    before do

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

        /**

         * @xtype foo

         */

        Ext.define('MyClass', {

          alias: 'widget.xxx'

        });

      EOS

    end

    it_should_behave_like "single xtype"

  end



  describe "Ext.define() with array of aliases" do

    before do

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

        /** */

        Ext.define('MyClass', {

          alias: ['widget.foo', 'widget.bar']

        });

      EOS

    end

    it_should_behave_like "multiple xtypes"

  end



  describe "Ext.define() with different kinds of aliases" do

    before do

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

        /** */

        Ext.define('MyClass', {

          alias: ['store.json', 'store.ajax', 'component.myclass']

        });

      EOS

    end

    it "collects all aliases together" do

      @doc[:xtypes].should == {"store" => ["json", "ajax"], "component" => ["myclass"]}

    end

  end



  describe "Ext.define() with xtype property" do

    before do

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

        /** */

        Ext.define('MyClass', {

          xtype: 'foo'

        });

      EOS

    end

    it_should_behave_like "single xtype"

  end



  describe "Ext.define() with array xtype property" do

    before do

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

        /** */

        Ext.define('MyClass', {

          xtype: ['foo', 'bar']

        });

      EOS

    end

    it_should_behave_like "multiple xtypes"

  end



  describe "Ext.define() with both xtype and alias" do

    before do

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

        /** */

        Ext.define('MyClass', {

          xtype: 'foo',

          alias: 'widget.bar'

        });

      EOS

    end

    it_should_behave_like "multiple xtypes"

  end



  describe "one class many times" do

    before do

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

        /**

         * @class Foo

         */

        /**

         * @class Foo

         * @xtype foo

         */

        /**

         * @class Foo

         * @xtype bar

         */

      EOS

    end

    it_should_behave_like "multiple xtypes"

  end



end