jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/js_parser.rb

@@ -1,221 +0,0 @@
-require 'jsduck/esprima'
-require 'jsduck/logger'
-
-module JsDuck
-
-  # JavaScript parser that internally uses Esprima.js
-  class JsParser
-
-    # Initializes the parser with JavaScript source code to be parsed.
-    def initialize(input, options = {})
-      @input = input
-
-      # Initialize line number counting
-      @start_index = 0
-      @start_linenr = 1
-    end
-
-    # Parses JavaScript source code and returns array of hashes like this:
-    #
-    #     {
-    #         :comment => "The contents of the comment",
-    #         :code => {...AST data structure for code following the comment...},
-    #         :linenr => 12,  // Beginning with 1
-    #         :type => :doc_comment, // or :plain_comment
-    #     }
-    #
-    def parse
-      @ast = Esprima.parse(@input)
-
-      @ast["comments"] = merge_comments(@ast["comments"])
-      locate_comments
-    end
-
-    private
-
-    # Merges consecutive line-comments and Establishes links between
-    # comments, so we can easily use comment["next"] to get to the
-    # next comment.
-    def merge_comments(original_comments)
-      result = []
-
-      comment = original_comments[0]
-      i = 0
-
-      while comment
-        i += 1
-        next_comment = original_comments[i]
-
-        if next_comment && mergeable?(comment, next_comment)
-          # Merge next comment to current one
-          comment["value"] += "\n" + next_comment["value"]
-          comment["range"][1] = next_comment["range"][1]
-        else
-          # Create a link and continue with next comment
-          comment["next"] = next_comment
-          result << comment
-          comment = next_comment
-        end
-      end
-
-      result
-    end
-
-    # Two comments can be merged if they are both line-comments and
-    # they are separated only by whitespace (only one newline at the
-    # end of the first comment is allowed)
-    def mergeable?(c1, c2)
-      if c1["type"] == "Line" && c2["type"] == "Line"
-        /\A(\r\n|\n|\r)?[ \t]*\Z/ =~ @input.slice((c1["range"][1])..(c2["range"][0]-1))
-      else
-        false
-      end
-    end
-
-    def locate_comments
-      @ast["comments"].map do |comment|
-        # Detect comment type and strip * at the beginning of doc-comment
-        value = comment["value"]
-        if comment["type"] == "Block" && value =~ /\A\*/
-          type = :doc_comment
-          value = value.slice(1, value.length-1)
-        else
-          type = :plain_comment
-        end
-
-        {
-          :comment => value,
-          :code => stuff_after(comment),
-          :linenr => line_number(comment["range"][0]),
-          :type => type,
-        }
-      end
-    end
-
-    # Given index inside input string, returns the corresponding line number
-    def line_number(index)
-      # To speed things up, remember the index until which we counted,
-      # then next time just begin counting from there.  This way we
-      # only count each line once.
-      @start_linenr = @input[@start_index...index].count("\n") + @start_linenr
-      @start_index = index
-      return @start_linenr
-    end
-
-    # Sees if there is some code following the comment.
-    # Returns the code found.  But if the comment is instead
-    # followed by another comment, returns nil.
-    def stuff_after(comment)
-      code = code_after(comment["range"], @ast)
-      if code && comment["next"]
-        return code["range"][0] < comment["next"]["range"][0] ? code : nil
-      else
-        code
-      end
-    end
-
-    # Looks for code following the given range.
-    #
-    # The second argument is the parent node within which we perform
-    # our search.
-    def code_after(range, parent)
-      # Look through all child nodes of parent...
-      child_nodes(parent).each do |node|
-        if less(range, node["range"])
-          # If node is after our range, then that's it.  There could
-          # be comments in our way, but that's taken care of in
-          # #stuff_after method.
-          return node
-        elsif within(range, node["range"])
-          # Our range is within the node --> recurse
-          return code_after(range, node)
-        end
-      end
-
-      return nil
-    end
-
-
-    # True if range A is less than range B
-    def less(a, b)
-      return a[1] <= b[0]
-    end
-
-    # True if range A is greater than range B
-    def greater(a, b)
-      return a[0] >= b[1]
-    end
-
-    # True if range A is within range B
-    def within(a, b)
-      return b[0] <= a[0] && a[1] <= b[1]
-    end
-
-
-    # Returns array of child nodes of given node
-    def child_nodes(node)
-      properties = NODE_TYPES[node["type"]]
-
-      unless properties
-        Logger.fatal("Unknown node type: "+node["type"])
-        exit(1)
-      end
-
-      properties.map {|p| node[p] }.compact.flatten
-    end
-
-    # All possible node types in Esprima-created abstract syntax tree
-    #
-    # Each node type maps to list of properties of that node into
-    # which we can recurse for further parsing.
-    NODE_TYPES = {
-      "Program" => ["body"],
-
-      "BlockStatement" => ["body"],
-      "BreakStatement" => [],
-      "ContinueStatement" => [],
-      "DoWhileStatement" => ["body", "test"],
-      "DebuggerStatement" => [],
-      "EmptyStatement" => [],
-      "ExpressionStatement" => ["expression"],
-      "ForStatement" => ["init", "test", "update", "body"],
-      "ForInStatement" => ["left", "right", "body"],
-      "IfStatement" => ["test", "consequent", "alternate"],
-      "LabeledStatement" => ["body"],
-      "ReturnStatement" => ["argument"],
-      "SwitchStatement" => ["discriminant", "cases"],
-      "SwitchCase" => ["test", "consequent"],
-      "ThrowStatement" => ["argument"],
-      "TryStatement" => ["block", "handlers", "finalizer"],
-      "CatchClause" => ["param", "body"],
-      "WhileStatement" => ["test", "body"],
-      "WithStatement" => ["object", "body"],
-
-      "FunctionDeclaration" => ["id", "params", "body"],
-      "VariableDeclaration" => ["declarations"],
-      "VariableDeclarator" => ["id", "init"],
-
-      "AssignmentExpression" => ["left", "right"],
-      "ArrayExpression" => ["elements"],
-      "BinaryExpression" => ["left", "right"],
-      "CallExpression" => ["callee", "arguments"],
-      "ConditionalExpression" => ["test", "consequent", "alternate"],
-      "FunctionExpression" => ["body"],
-
-      "LogicalExpression" => ["left", "right"],
-      "MemberExpression" => ["object", "property"],
-      "NewExpression" => ["callee", "arguments"],
-      "ObjectExpression" => ["properties"],
-      "Property" => ["key", "value"],
-
-      "SequenceExpression" => ["expressions"],
-      "ThisExpression" => [],
-      "UnaryExpression" => ["argument"],
-      "UpdateExpression" => ["argument"],
-
-      "Identifier" => [],
-      "Literal" => [],
-    }
-
-  end
-end

data/lib/jsduck/lint.rb

@@ -1,133 +0,0 @@
-require 'jsduck/logger'
-require 'jsduck/class'
-
-module JsDuck
-
-  # Reports bugs and problems in documentation
-  class Lint
-    attr_accessor :relations
-
-    def initialize(relations)
-      @relations = relations
-    end
-
-    # Runs the linter
-    def run
-      warn_no_doc
-      warn_unnamed
-      warn_optional_params
-      warn_duplicate_params
-      warn_duplicate_members
-      warn_singleton_statics
-      warn_empty_enums
-    end
-
-    # print warning for each member or parameter with no name
-    def warn_unnamed
-      each_member do |member|
-        if !member[:name] || member[:name] == ""
-          warn(:name_missing, "Unnamed #{member[:tagname]}", member)
-        end
-        (member[:params] || []).each do |p|
-          if !p[:name] || p[:name] == ""
-            warn(:name_missing, "Unnamed parameter", member)
-          end
-        end
-      end
-    end
-
-    # print warning for each class or public member with no name
-    def warn_no_doc
-      @relations.each do |cls|
-        if cls[:doc] == ""
-          warn(:no_doc, "No documentation for #{cls[:name]}", cls)
-        end
-      end
-      each_member do |member|
-        if member[:doc] == "" && !member[:private] && !member[:meta][:hide] && !JsDuck::Class.constructor?(member)
-          warn(:no_doc, "No documentation for #{member[:owner]}##{member[:name]}", member)
-        end
-      end
-    end
-
-    # print warning for each non-optional parameter that follows an optional parameter
-    def warn_optional_params
-      each_member do |member|
-        if member[:tagname] == :method
-          optional_found = false
-          member[:params].each do |p|
-            if optional_found && !p[:optional]
-              warn(:req_after_opt, "Optional param followed by regular param #{p[:name]}", member)
-            end
-            optional_found = optional_found || p[:optional]
-          end
-        end
-      end
-    end
-
-    # print warnings for duplicate parameter names
-    def warn_duplicate_params
-      each_member do |member|
-        params = {}
-        (member[:params] || []).each do |p|
-          if params[p[:name]]
-            warn(:dup_param, "Duplicate parameter name #{p[:name]}", member)
-          end
-          params[p[:name]] = true
-        end
-      end
-    end
-
-    # print warnings for duplicate member names
-    def warn_duplicate_members
-      @relations.each do |cls|
-        members = {:members => {}, :statics => {}}
-        cls.all_local_members.each do |m|
-          group = (m[:meta] && m[:meta][:static]) ? :statics : :members
-          type = m[:tagname]
-          name = m[:name]
-          hash = members[group][type] || {}
-          if hash[name]
-            warn(:dup_member, "Duplicate #{type} name #{name}", hash[name])
-            warn(:dup_member, "Duplicate #{type} name #{name}", m)
-          end
-          hash[name] = m
-          members[group][type] = hash
-        end
-      end
-    end
-
-    # Print warnings for static members in singleton classes
-    def warn_singleton_statics
-      @relations.each do |cls|
-        if cls[:singleton]
-          cls.find_members({:local => true, :static => true}).each do |m|
-            warn(:sing_static, "Static members don't make sense in singleton class #{cls[:name]}", m)
-          end
-        end
-      end
-    end
-
-    # print warnings for enums with no values
-    def warn_empty_enums
-      @relations.each do |cls|
-        if cls[:enum] && cls[:members].length == 0
-          warn(:enum, "Enum #{cls[:name]} defined without values in it", cls)
-        end
-      end
-    end
-
-    # Loops through all members of all classes
-    def each_member(&block)
-      @relations.each {|cls| cls.all_local_members.each(&block) }
-    end
-
-    # Prints warning + filename and linenumber from doc-context
-    def warn(type, msg, member)
-      context = member[:files][0]
-      Logger.warn(type, msg, context[:filename], context[:linenr])
-    end
-
-  end
-
-end

data/lib/jsduck/meta_tag.rb

@@ -1,88 +0,0 @@
-module JsDuck
-
-  # Abstract base class for all meta tag implementations.
-  #
-  # Child classes must define value for @name attribute.  They can
-  # also provide @multiline, and override #to_html method.
-  class MetaTag
-    # Name of the tag (required)
-    attr_reader :name
-
-    # The key under which to store this tag. Must be a symbol.  When
-    # not provided then :name is converted to symbol and used as key.
-    attr_accessor :key
-
-    # The text to display in member signature.  Must be a hash
-    # defining the short and long versions of the signature text:
-    #
-    #     {:long => "something", :short => "SOM"}
-    #
-    # Additionally the hash can contain a :tooltip which is the text
-    # to be shown when the signature bubble is hovered over in docs.
-    attr_reader :signature
-
-    # True to include all lines up to next @tag as part of this meta-tag
-    attr_reader :multiline
-
-    # True to ignore any text after the @tag, just record the
-    # existance of the tag.
-    attr_reader :boolean
-
-    # Whether to render the tag before other content (:top) or after
-    # it (:bottom).  Defaults to :bottom.
-    attr_accessor :position
-
-    # Here the appropriate class or member will be injected,
-    # so the to_value and to_html methods can for produce
-    # different output based on whether the tag is inside class,
-    # method, event, etc.
-    attr_accessor :context
-
-    # Here the Assets object will be injected, so the Tag implementation
-    # can access guides, videos, etc when he needs to.
-    attr_accessor :assets
-
-    # It gets passed an array of contents gathered from all meta-tags
-    # of given type. It should return the value to be stored for this
-    # meta-tag at :key. The returned value is also passed to #to_html
-    # method. Returning nil will cause the tag to be ignored. By
-    # default the contents are returned unchanged.
-    def to_value(contents)
-      contents
-    end
-
-    # Override this to transform the content of meta-tag to HTML to be
-    # included into documentation.
-    #
-    # It gets passed the value returned by #to_value method. It should
-    # return an HTML string to inject into document.  For help in that
-    # it can use the #format method to easily support Markdown and
-    # {@link/img} tags inside the contents of meta-tag.
-    #
-    # By default the method returns nil, which means the tag will not
-    # be rendered at all.
-    def to_html(contents)
-    end
-
-    # This is used to inject the formatter object for #markdown method
-    attr_accessor :formatter
-
-    # Helper method to format the text in standard JsDuck way.
-    # This means running it through Markdown engine and expanding
-    # {@link} and {@img} tags.
-    def format(text)
-      @formatter.format(text)
-    end
-
-    # Returns all descendants of MetaTag class.
-    def self.descendants
-      result = []
-      ObjectSpace.each_object(::Class) do |cls|
-        result << cls if cls < self
-      end
-      result
-    end
-
-  end
-
-end

data/lib/jsduck/meta_tag_loader.rb

@@ -1,67 +0,0 @@
-require "jsduck/meta_tag"
-
-module JsDuck
-
-  # Loader for built-in and user-defined meta-tags.
-  class MetaTagLoader
-    attr_reader :meta_tags
-
-    def initialize
-      @classes = []
-      @meta_tags = []
-    end
-
-    # Loads user-defined meta-tags from given path.
-    #
-    # * If path is a directory, loads all *.rb files in it.
-    # * If path is the symbol :builtins, loads the builtin
-    #   tags from ./tag dir.
-    # * Otherwise loads tags from the single file.
-    def load(path)
-      if path == :builtins
-        load(File.dirname(__FILE__) + "/tag")
-      elsif File.directory?(path)
-        # Sort paths, so they are always loaded in the same order.
-        # This is important for signatures to always be rendered in
-        # the same order.
-        Dir[path+"/**/*.rb"].sort.each {|file| load_file(file) }
-      else
-        load_file(path)
-      end
-    end
-
-    private
-
-    # Loads just one file.
-    def load_file(file)
-      require(file)
-      init_remaining
-    end
-
-    # Instantiates meta tag classes that haven't been instantiated
-    # already. This is called after each meta-tags file is loaded so
-    # that the list of meta-tags will be in order specified from
-    # command line.
-    def init_remaining
-      MetaTag.descendants.each do |cls|
-        if !@classes.include?(cls)
-          @classes << cls
-          newtag = create_tag(cls)
-          @meta_tags = @meta_tags.find_all {|t| t.name != newtag.name }
-          @meta_tags << newtag
-        end
-      end
-    end
-
-    # Instanciates tag class.
-    # When .key is missing, creates it from .name
-    # When .position is missing, defaults to :bottom
-    def create_tag(cls)
-      tag = cls.new
-      tag.key = tag.name.to_sym unless tag.key
-      tag.position = :bottom unless tag.position
-      tag
-    end
-  end
-
-end