Class: JsDuck::InheritDoc

Inherits:
Object
  • Object
show all
Defined in:
lib/jsduck/inherit_doc.rb

Overview

Deals with inheriting documentation

Instance Method Summary collapse

Constructor Details

#initialize(relations) ⇒ InheritDoc

Returns a new instance of InheritDoc.



8
9
10
 
# File 'lib/jsduck/inherit_doc.rb', line 8

def initialize(relations)
  @relations = relations
end

Instance Method Details

#find_class_parent(cls) ⇒ Object 



89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/jsduck/inherit_doc.rb', line 89

def find_class_parent(cls)
  if cls[:inheritdoc][:cls]
    # @inheritdoc MyClass
    parent = @relations[cls[:inheritdoc][:cls]]
    return warn("class not found", cls) unless parent
  else
    # @inheritdoc
    parent = cls.parent
    return warn("parent class not found", cls) unless parent
  end

  return parent[:inheritdoc] ? find_class_parent(parent) : parent
end

#find_parent(m) ⇒ Object

Finds parent member of the given member. When @inheritdoc names a member to inherit from, finds that member instead.

If the parent also has @inheritdoc, continues recursively.



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/jsduck/inherit_doc.rb', line 36

def find_parent(m)
  if m[:inheritdoc][:cls]
    # @inheritdoc MyClass#member
    parent_cls = @relations[m[:inheritdoc][:cls]]
    return warn("class not found", m) unless parent_cls

    parent = lookup_member(parent_cls, m)
    return warn("member not found", m) unless parent

  elsif m[:inheritdoc][:member]
    # @inheritdoc #member
    parent = lookup_member(@relations[m[:owner]], m)
    return warn("member not found", m) unless parent

  else
    # @inheritdoc
    parent_cls = @relations[m[:owner]].parent
    mixins = @relations[m[:owner]].mixins

    # Warn when no parent or mixins at all
    return warn("parent class not found", m) unless parent_cls || mixins.length > 0

    # First check for the member in all mixins, because members
    # from mixins override those from parent class.  Looking first
    # from mixins is probably a bit slower, but it's the correct
    # order to do things.
    if mixins.length > 0
      parent = mixins.map {|mix| lookup_member(mix, m) }.compact.first
    end

    # When not found, try looking from parent class
    if !parent && parent_cls
      parent = lookup_member(parent_cls, m)
    end

    # Only when both parent and mixins fail, throw warning
    return warn("parent member not found", m) unless parent
  end

  return parent[:inheritdoc] ? find_parent(parent) : parent
end

#lookup_member(cls, m) ⇒ Object 



78
79
80
81
 
# File 'lib/jsduck/inherit_doc.rb', line 78

def lookup_member(cls, m)
  inherit = m[:inheritdoc]
  cls.get_members(inherit[:member] || m[:name], inherit[:type] || m[:tagname], inherit[:static] || m[:meta][:static])[0]
end

#resolve(m) ⇒ Object

Copy over doc/params/return from parent member.



25
26
27
28
29
30
 
# File 'lib/jsduck/inherit_doc.rb', line 25

def resolve(m)
  parent = find_parent(m)
  m[:doc] = (m[:doc] + "\n\n" + parent[:doc]).strip
  m[:params] = parent[:params] if parent[:params]
  m[:return] = parent[:return] if parent[:return]
end

#resolve_all ⇒ Object

Performs all inheriting



13
14
15
16
17
18
19
20
21
22
 
# File 'lib/jsduck/inherit_doc.rb', line 13

def resolve_all
  @relations.each do |cls|
    resolve_class(cls) if cls[:inheritdoc]
    cls.all_local_members.each do |member|
      if member[:inheritdoc]
        resolve(member)
      end
    end
  end
end

#resolve_class(cls) ⇒ Object

Copy over doc from parent class.



84
85
86
87
 
# File 'lib/jsduck/inherit_doc.rb', line 84

def resolve_class(cls)
  parent = find_class_parent(cls)
  cls[:doc] = (cls[:doc] + "\n\n" + parent[:doc]).strip
end

#warn(msg, item) ⇒ Object 



103
104
105
106
107
108
109
110
111
 
# File 'lib/jsduck/inherit_doc.rb', line 103

def warn(msg, item)
  context = item[:files][0]
  i_member = item[:inheritdoc][:member]

  msg = "@inheritdoc #{item[:inheritdoc][:cls]}"+ (i_member ? "#" + i_member : "") + " - " + msg
  Logger.instance.warn(:inheritdoc, msg, context[:filename], context[:linenr])

  return item
end