jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/guide_anchors.rb

@@ -1,32 +0,0 @@
-module JsDuck
-
-  # Transforms in-page links so they won't break docs app #!-navigation.
-  #
-  # For example a link to "#automation" in testing guide will be
-  # replaced with "#!/guide/testing-section-automation" and the link
-  # target ID will be transformed into "testing-section-automation".
-  class GuideAnchors
-
-    def self.transform(html, guide_name)
-      html.gsub(/(<a\s+(?:[^<>]*\s+)?href=['"]#)([^!\/].*?)(['"])/i) do |m|
-        "#{$1}!/guide/#{guide_name}-section-#{$2}#{$3}"
-
-      end.gsub(/(<a\s+(?:[^<>]*\s+)?name=['"])(.*?)(['"])/i) do |m|
-        $1 + transform_id($2, guide_name) + $3
-
-      end.gsub(/(<\w+\s+(?:[^<>]*\s+)?id=['"])(.*?)(['"])/i) do |m|
-        $1 + transform_id($2, guide_name) + $3
-      end
-    end
-
-    def self.transform_id(id, guide_name)
-      if id =~ /^#{guide_name}-section-/
-        id
-      else
-        "#{guide_name}-section-#{id}"
-      end
-    end
-
-  end
-
-end

data/lib/jsduck/guide_toc.rb

@@ -1,49 +0,0 @@
-require 'jsduck/util/html'
-
-module JsDuck
-
-  # Adds Table of Contents section to guide HTML.
-  class GuideToc
-
-    # Inserts table of contents at the top of guide HTML by looking
-    # for <h2> elements.
-    def self.inject(html, guide_name)
-      toc = []
-      new_html = []
-
-      html.each_line do |line|
-        if line =~ /^\s*<(h[1-6])>(.*?)<\/h[1-6]>$/
-          tag = $1
-          text = Util::HTML.strip_tags($2)
-          id = guide_name + "-section-" + title_to_id(text)
-          if tag == "h2"
-            toc << "<li><a href='#!/guide/#{id}'>#{text}</a></li>\n"
-          end
-          new_html << "<#{tag} id='#{id}'>#{text}</#{tag}>\n"
-        else
-          new_html << line
-        end
-      end
-
-      # Inject TOC below first heading if at least 2 items in TOC
-      if toc.length >= 2
-        new_html.insert(1, [
-            "<div class='toc'>\n",
-            "<p><strong>Contents</strong></p>\n",
-            "<ol>\n",
-            toc,
-            "</ol>\n",
-            "</div>\n",
-        ])
-      end
-
-      new_html.flatten.join
-    end
-
-    def self.title_to_id(title)
-      title.downcase.gsub(/[^\w]+/, "-")
-    end
-
-  end
-
-end

data/lib/jsduck/html_stack.rb

@@ -1,105 +0,0 @@
-require 'jsduck/logger'
-
-module JsDuck
-
-  # Tracks opening and closing of HTML tags, with the purpose of
-  # closing down the unfinished tags.
-  class HtmlStack
-
-    # Initializes the stack with two optional parameters:
-    #
-    # @param ignore_html A hash of additional HTML tags that don't need closing.
-    # @param doc_context Filename and linenr of the current doc-comment.
-    def initialize(ignore_html={}, doc_context={})
-      @ignore_html = ignore_html
-      @doc_context = doc_context
-      @open_tags = []
-    end
-
-    # Scans an opening tag in HTML using the passed in StringScanner.
-    def open(s)
-      s.scan(/</) + push_tag(s.scan(/\w+/)) + s.scan_until(/>|\Z/)
-    end
-
-    # Scans a closing tag in HTML using the passed in StringScanner.
-    def close(s)
-      s.scan(/<\//)
-      tag = s.scan(/\w+/)
-      s.scan(/>/)
-
-      pop_tags(tag).map {|t| "</#{t}>" }.join
-    end
-
-    # Registers opening of a tag.  Returns the tag.
-    def push_tag(tag)
-      @open_tags.push(tag) unless void?(tag)
-      tag
-    end
-
-    # True when the tag is currently open.
-    def open?(tag)
-      @open_tags.include?(tag)
-    end
-
-    private
-
-    # Registers closing of a tag.  Returns all the tags that need to
-    # be closed at that point.
-    def pop_tags(tag)
-      if !@open_tags.include?(tag)
-        if @ignore_html[tag]
-          return [tag]
-        else
-          warn_unopened(tag)
-          return []
-        end
-      end
-
-      popped = []
-      begin
-        popped << t = @open_tags.pop
-        if t != tag
-          warn_unclosed(t)
-        end
-      end until t == tag
-
-      popped
-    end
-
-    def warn_unopened(*tags)
-      warn("Unopened HTML tag", tags)
-    end
-
-    def warn_unclosed(*tags)
-      warn("Unclosed HTML tag", tags)
-    end
-
-    def warn(msg, tags)
-      ctx = @doc_context
-      tag_list = tags.map {|tag| "<#{tag}>" }.join(", ")
-      Logger.warn(:html, "#{msg}: #{tag_list}", ctx[:filename], ctx[:linenr])
-    end
-
-    def void?(tag)
-      VOID_TAGS[tag] || @ignore_html[tag]
-    end
-
-    # Tags that don't require closing
-    VOID_TAGS = {
-      "base" => true,
-      "link" => true,
-      "meta" => true,
-      "hr" => true,
-      "br" => true,
-      "wbr" => true,
-      "area" => true,
-      "img" => true,
-      "param" => true,
-      "input" => true,
-      "isindex" => true,
-      "option" => true,
-    }
-
-  end
-
-end

data/lib/jsduck/importer.rb

@@ -1,121 +0,0 @@
-require 'jsduck/util/json'
-require 'jsduck/util/null_object'
-require 'jsduck/logger'
-require 'jsduck/util/parallel'
-
-module JsDuck
-
-  # Reads in JSDuck exports of different versions of docs.
-  module Importer
-    module_function
-
-    # Loads in exported docs and generates @since and @new tags based on that data.
-    def import(imports, relations, new_since=nil)
-      if imports.length > 0
-        generate_since_tags(read_all(imports), relations, new_since)
-      end
-    end
-
-    # 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).
-    def read_all(imports)
-      imports.map do |ver|
-        {
-          :version => ver[:version],
-          :classes => ver[:path] ? read(ver) : current_version,
-        }
-      end
-    end
-
-    def current_version
-      Util::NullObject.new(:[] => Util::NullObject.new(:[] => true))
-    end
-
-    # Reads in data from all .json files in directory
-    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
-
-    # creates index of all class members
-    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
-
-    # Using the imported versions data, adds @since tags to all
-    # classes/members.
-    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
-
-    # 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.
-    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
-
-    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
-
-    # Returns name of the version since which the class is available
-    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
-
-  end
-
-end

data/lib/jsduck/inherit_doc.rb

@@ -1,193 +0,0 @@
-require 'jsduck/logger'
-require 'jsduck/class'
-
-module JsDuck
-
-  # Deals with inheriting documentation
-  class InheritDoc
-    def initialize(relations)
-      @relations = relations
-    end
-
-    # Performs all inheriting
-    def resolve_all
-      @relations.each do |cls|
-        resolve_class(cls) if cls[:inheritdoc]
-
-        new_cfgs = []
-        cls.all_local_members.each do |member|
-          if member[:inheritdoc]
-            resolve(member, new_cfgs)
-          end
-        end
-        move_cfgs(cls, new_cfgs) if new_cfgs.length > 0
-      end
-    end
-
-    private
-
-    # Copy over doc/params/return from parent member.
-    def resolve(m, new_cfgs)
-      parent = find_parent(m)
-
-      if m[:inheritdoc] && parent
-        m[:doc] = (m[:doc] + "\n\n" + parent[:doc]).strip
-        m[:params] = parent[:params] if parent[:params]
-        m[:return] = parent[:return] if parent[:return]
-        m[:type] = parent[:type] if parent[:type]
-
-        if m[:autodetected]
-          m[:meta] = parent[:meta].merge(m[:meta])
-        end
-
-        # remember properties that have changed to configs
-        if m[:autodetected] && m[:tagname] != parent[:tagname]
-          new_cfgs << m
-        end
-      end
-
-      resolve_visibility(m, parent)
-    end
-
-    # Changes given properties into configs within class
-    def move_cfgs(cls, members)
-      members.each do |m|
-        m[:tagname] = :cfg
-      end
-      # Ask class to update its internal caches for these members
-      cls.update_members!(members)
-    end
-
-    # For auto-detected members/classes (which have @private == :inherit)
-    # Use the visibility from parent class (defaulting to private when no parent).
-    def resolve_visibility(m, parent)
-      if m[:autodetected] && !JsDuck::Class.constructor?(m)
-        if !parent || parent[:private]
-          m[:meta][:private] = m[:private] = true
-        end
-      end
-    end
-
-    # 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.
-    def find_parent(m)
-
-      inherit = m[:inheritdoc] || {}
-      if inherit[: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 inherit[: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
-        if !parent_cls && mixins.length == 0
-          warn("parent class not found", m) unless m[:autodetected]
-          return nil
-        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 {|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
-        if !parent
-          warn("parent member not found", m) unless m[:autodetected]
-          return nil
-        end
-      end
-
-      return parent[:inheritdoc] ? find_parent(parent) : parent
-    end
-
-    def lookup_member(cls, m)
-      inherit = m[:inheritdoc] || {}
-      name = inherit[:member] || m[:name]
-      tagname = inherit[:type] || m[:tagname]
-      static = inherit[:static] || m[:meta][:static]
-
-      if m[:autodetected]
-        # Auto-detected properties can override either a property or a
-        # config. So look for both types.
-        if tagname == :property
-          cfg = cls.find_members(:name => name, :tagname => :cfg, :static => static || false)[0]
-          prop = cls.find_members(:name => name, :tagname => :property, :static => static || false)[0]
-
-          if cfg && prop
-            prop
-          elsif cfg
-            cfg
-          elsif prop
-            prop
-          else
-            nil
-          end
-
-        else
-          # Unless the auto-detected member is detected as static,
-          # look only at instance members.
-          cls.find_members(:name => name, :tagname => tagname, :static => static || false)[0]
-        end
-      else
-        cls.find_members(:name => name, :tagname => tagname, :static => static)[0]
-      end
-    end
-
-    # Copy over doc from parent class.
-    def resolve_class(cls)
-      parent = find_class_parent(cls)
-
-      if parent
-        cls[:doc] = (cls[:doc] + "\n\n" + parent[:doc]).strip
-      end
-    end
-
-    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
-
-    def warn(msg, item)
-      context = item[:files][0]
-      i_member = item[:inheritdoc][:member]
-
-      msg = "@inheritdoc #{item[:inheritdoc][:cls]}"+ (i_member ? "#" + i_member : "") + " - " + msg
-      Logger.warn(:inheritdoc, msg, context[:filename], context[:linenr])
-
-      return nil
-    end
-
-  end
-
-end