Commit 807060c2 authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Let private members hide public members of parent class. 

For example:

    /** @class Parent */
      /** @method foo */

    /** @class Child @extends Parent */
      /** @method foo @private */

Previously this resulted in Child class docs having method foo from
Parent, as if the private foo in Child didn't exist at all.  This
behavior was quite far from obvious.

Now the Child class docs will have no foo method at all - the parent
class method gets shadowed with @private foo in subclass.  This should
be more like what the documentation author intended.

As a bonus we now have better error messages for cases where {@link}
refers to a private member, and @inheritdoc can be used to inherit
docs from private members.
parent 80ac93b8

lib/jsduck/class.rb

+4 −3
Original line number Diff line number Diff line
@@ -89,7 +89,8 @@ module JsDuck 
    #

    # See members_hash for details.

    def members(type, context=:members)

      ms = members_hash(type, context).values.sort {|a,b| a[:name] <=> b[:name] }

      ms = members_hash(type, context).values.find_all {|m| !m[:private] }

      ms.sort! {|a,b| a[:name] <=> b[:name] }

      type == :method ? constructor_first(ms) : ms

    end
@@ -104,7 +105,7 @@ module JsDuck 
      ms

    end



    # Returns hash of public members of class (and of parent classes

    # Returns hash of all members in class (and of parent classes

    # and mixin classes).  Members are methods, properties, cfgs,

    # events (member type is specified through 'type' parameter).

    #
@@ -148,7 +149,7 @@ module JsDuck 
    def local_members_hash(type, context)

      local_members = {}

      (@doc[context][type] || []).each do |m|

        local_members[m[:name]] = m if !m[:private]

        local_members[m[:name]] = m

      end

      local_members

    end

lib/jsduck/doc_formatter.rb

+10 −2
Original line number Diff line number Diff line
@@ -135,6 +135,9 @@ module JsDuck 
        elsif member && !get_member(cls, member, type)

          Logger.instance.warn(:link, "#{input} links to non-existing member", file, line)

          text

        elsif member && !public_member?(cls, member, type)

          Logger.instance.warn(:link, "#{input} links to private member", file, line)

          text

        else

          link(cls, member, text, type)

        end
@@ -153,7 +156,7 @@ module JsDuck 
        member = $4

        after = $5



        if @relations[cls] && (member ? get_member(cls, member) : cls =~ /\./)

        if @relations[cls] && (member ? public_member?(cls, member) : cls =~ /\./)

          label = member ? cls+"."+member : cls

          before + link(cls, member, label) + after

        else
@@ -202,8 +205,13 @@ module JsDuck 
      end

    end



    def public_member?(cls, member, type=nil)

      m = get_member(cls, member, type)

      return m && !m[:private]

    end



    def get_member(cls, member, type=nil)

      @relations[cls] && @relations[cls].get_member(member, type)

      return @relations[cls] && @relations[cls].get_member(member, type)

    end



    # Formats doc-comment for placement into HTML.

spec/class_spec.rb

+11 −4
Original line number Diff line number Diff line
@@ -19,6 +19,7 @@ describe JsDuck::Class do 
              {:name => "foo", :owner => "ParentClass"},

              {:name => "constructor", :owner => "ParentClass"},

              {:name => "frank", :owner => "ParentClass", :private => true},

              {:name => "zappa", :owner => "ParentClass", :private => true},

            ]

          },

          :statics => {
@@ -95,9 +96,15 @@ describe JsDuck::Class do 
      @members.first[:name].should == "constructor"

    end



    def members_as_hash(cls, type, context=:members)

      h = {}

      cls.members(type, context).each {|m| h[m[:name]] = m }

      h

    end



    describe "(:method)" do

      before do

        @members = @child.members_hash(:method)

        @members = members_as_hash(@child, :method)

      end



      it "returns all public members in current class" do
@@ -140,7 +147,7 @@ describe JsDuck::Class do 


      describe "singleton class" do

        before do

          @members = @singletonChild.members_hash(:method)

          @members = members_as_hash(@singletonChild, :method)

        end



        it "inherits all instance members from parent" do
@@ -164,7 +171,7 @@ describe JsDuck::Class do 


    describe "(:method, :statics)" do

      before do

        @members = @child.members_hash(:method, :statics)

        @members = members_as_hash(@child, :method, :statics)

      end



      it "returns normal statics in current class" do
@@ -193,7 +200,7 @@ describe JsDuck::Class do 


      describe "singleton class" do

        before do

          @members = @singletonChild.members_hash(:method, :statics)

          @members = members_as_hash(@singletonChild, :method, :statics)

        end



        it "doesn't inherit any static members from parent" do