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_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.



35
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
77
78
79
80
81
82
83
 
# File 'lib/jsduck/inherit_doc.rb', line 35

def find_parent(m)
  context = m[:files][0]
  inherit = m[:inheritdoc]

  if inherit[:cls]
    parent_cls = @relations[inherit[:cls]]
    unless parent_cls
      warn("@inheritdoc #{inherit[:cls]}##{inherit[:member]} - class not found", context)
      return m
    end
    parent = parent_cls.get_members(inherit[:member], inherit[:type] || m[:tagname], inherit[:static] || m[:meta][:static])[0]
    unless parent
      warn("@inheritdoc #{inherit[:cls]}##{inherit[:member]} - member not found", context)
      return m
    end
  else
    parent_cls = @relations[m[:owner]].parent
    mixins = @relations[m[:owner]].mixins
    # Warn when no parent or mixins at all
    if !parent_cls && mixins.length == 0
      warn("@inheritdoc - parent class not found", context)
      return m
    end
    # 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 do |mix|
        mix.get_members(m[:name], m[:tagname], m[:meta][:static])[0]
      end.compact.first
    end
    # When not found, try looking from parent class
    if !parent && parent_cls
      parent = parent_cls.get_members(m[:name], m[:tagname], m[:meta][:static])[0]
    end
    # Only when both parent and mixins fail, throw warning
    if !parent
      warn("@inheritdoc - parent member not found", context)
      return m
    end
  end

  if parent[:inheritdoc]
    find_parent(parent)
  else
    parent
  end
end

#resolve(m) ⇒ Object

Copy over doc/params/return from parent member.



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

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
 
# File 'lib/jsduck/inherit_doc.rb', line 13

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

#warn(msg, context) ⇒ Object 



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

def warn(msg, context)
  Logger.instance.warn(:inheritdoc, msg, context[:filename], context[:linenr])
end