Module: JsDuck::Importer

Defined in:
lib/jsduck/importer.rb

Overview

Reads in JSDuck exports of different versions of docs.

Class Method Summary collapse

Class Method Details

.build_new_versions_map(versions, new_since = nil) ⇒ Object

Generates a lookup table of versions that we are going to label with @new tags. By default we use the latest version, otherwise use all versions since the latest.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/jsduck/importer.rb', line 82

def build_new_versions_map(versions, new_since=nil)
  new_versions = {}

  if new_since
    versions.map {|v| v[:version] }.each do |v|
      if v == new_since || !new_versions.empty?
        new_versions[v] = true
      end
    end
  else
    new_versions[versions.last[:version]] = true
  end

  new_versions
end

.class_since(versions, cls) ⇒ Object

Returns name of the version since which the class is available



110
111
112
113
114
115
116
117
 
# File 'lib/jsduck/importer.rb', line 110

def class_since(versions, cls)
  versions.each do |ver|
    return ver[:version] if ver[:classes][cls[:name]]
    cls[:alternateClassNames].each do |name|
      return ver[:version] if ver[:classes][name]
    end
  end
end

.current_version ⇒ Object 



31
32
33
 
# File 'lib/jsduck/importer.rb', line 31

def current_version
  Util::NullObject.new(:[] => Util::NullObject.new(:[] => true))
end

.generate_since_tags(versions, relations, new_since = nil) ⇒ Object

Using the imported versions data, adds @since tags to all classes/members.



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/jsduck/importer.rb', line 63

def generate_since_tags(versions, relations, new_since=nil)
  new_versions = build_new_versions_map(versions, new_since)

  relations.each do |cls|
    v = cls[:meta][:since] || class_since(versions, cls)
    cls[:meta][:since] = v
    cls[:meta][:new] = true if new_versions[v]

    cls.all_local_members.each do |m|
      v = m[:meta][:since] || member_since(versions, cls, m)
      m[:meta][:since] = v
      m[:meta][:new] = true if new_versions[v]
    end
  end
end

.import(imports, relations, new_since = nil) ⇒ Object

Loads in exported docs and generates @since and @new tags based on that data.



13
14
15
16
17
 
# File 'lib/jsduck/importer.rb', line 13

def import(imports, relations, new_since=nil)
  if imports.length > 0
    generate_since_tags(read_all(imports), relations, new_since)
  end
end

.member_since(versions, cls, m) ⇒ Object 



98
99
100
101
102
103
104
105
106
107
 
# File 'lib/jsduck/importer.rb', line 98

def member_since(versions, cls, m)
  versions.each do |ver|
    c = ver[:classes][cls[:name]]
    return ver[:version] if c && c[m[:id]]
    cls[:alternateClassNames].each do |name|
      c = ver[:classes][name]
      return ver[:version] if c && c[m[:id]]
    end
  end
end

.members_id_index(json) ⇒ Object

creates index of all class members



49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/jsduck/importer.rb', line 49

def members_id_index(json)
  index = {}
  ["members", "statics"].each do |group_name|
    json[group_name].each_pair do |tagname, members|
      members.each do |m|
        index[m["id"]] = true
      end
    end
  end
  index
end

.read(ver) ⇒ Object

Reads in data from all .json files in directory



36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/jsduck/importer.rb', line 36

def read(ver)
  # Map list of files into pairs of (classname, members-hash)
  pairs = Util::Parallel.map(Dir[ver[:path] + "/*.json"]) do |filename|
    JsDuck::Logger.log("Importing #{ver[:version]}", filename)
    json = Util::Json.read(filename)
    [json["name"],  members_id_index(json)]
  end

  # Turn key-value pairs array into hash
  return Hash[ pairs ]
end

.read_all(imports) ⇒ Object

Reads in data for all versions, returning array of version/class-data pairs. We don’t use a hash to preserve the order of versions (from oldest to newest).



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

def read_all(imports)
  imports.map do |ver|
    {
      :version => ver[:version],
      :classes => ver[:path] ? read(ver) : current_version,
    }
  end
end