jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/doc/map.rb

@@ -0,0 +1,23 @@
+module JsDuck
+  module Doc
+
+    # Helper for building at-tags lookup table.
+    class Map
+
+      # Builds map of at-tags for quick lookup
+      def self.build(docs)
+        map = {}
+        docs.each do |tag|
+          if map[tag[:tagname]]
+            map[tag[:tagname]] << tag
+          else
+            map[tag[:tagname]] = [tag]
+          end
+        end
+        map
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/doc/parser.rb

@@ -0,0 +1,128 @@
+require 'strscan'
+require 'jsduck/doc/comment'
+require 'jsduck/doc/scanner'
+require 'jsduck/tag_registry'
+require 'jsduck/logger'
+
+module JsDuck
+  module Doc
+
+    # Parses doc-comment into array of @tags
+    #
+    # For each @tag it produces Hash like the following:
+    #
+    #     {
+    #       :tagname => :cfg/:property/:type/:extends/...,
+    #       :doc => "Some documentation for this tag",
+    #       ...@tag specific stuff like :name, :type, and so on...
+    #     }
+    #
+    # When doc-comment begins with comment, not preceded by @tag, then
+    # the comment will be placed into Hash with :tagname => :default.
+    #
+    # Unrecognized @tags are left as is into documentation as if they
+    # were normal text.
+    #
+    # @example, {@img}, {@link} and {@video} are parsed separately in
+    # JsDuck::DocFormatter.
+    #
+    class Parser < Doc::Scanner
+      def parse(input, filename="", linenr=0)
+        @filename = filename
+        @linenr = linenr
+        @tags = []
+        @input = StringScanner.new(Doc::Comment.purify(input))
+
+        parse_loop
+
+        strip_docs
+        @tags
+      end
+
+      # The parsing process can leave whitespace at the ends of
+      # doc-strings, here we get rid of it.
+      def strip_docs
+        @tags.each do |tag|
+          tag[:doc].strip! if tag[:doc]
+        end
+      end
+
+      # The main loop of the DocParser
+      def parse_loop
+        add_tag({:tagname => :doc, :doc => :multiline})
+
+        while !@input.eos? do
+          if look(/@/)
+            parse_at_tag
+          elsif look(/[^@]/)
+            skip_to_next_at_tag
+          end
+        end
+      end
+
+      # Appends new @tag to parsed tags list
+      def add_tag(tag)
+        @tags << tag
+
+        if tag[:doc] == :multiline
+          tag[:doc] = ""
+          @multiline_tag = tag
+        end
+      end
+
+      # Processes anything beginning with @-sign.
+      #
+      # - When @ is not followed by any word chars, do nothing.
+      # - When it's one of the builtin tags, process it as such.
+      # - When it's something else, print a warning.
+      #
+      def parse_at_tag
+        match(/@/)
+        name = look(/\w+/)
+
+        if !name
+          # ignore
+        elsif tag = TagRegistry.get_by_pattern(name)
+          match(/\w+/)
+          hw # Skip the whitespace right after the tag.
+
+          tags = tag.parse_doc(self)
+          if tags.is_a?(Hash)
+            add_tag(tags)
+          elsif tags.is_a?(Array)
+            tags.each {|t| add_tag(t) }
+          end
+
+          skip_white
+        else
+          Logger.warn(:tag, "Unsupported tag: @#{name}", @filename, @linenr)
+          @multiline_tag[:doc] += "@"
+        end
+      end
+
+      # Skips until the beginning of next @tag.
+      #
+      # There must be space before the next @tag - this ensures that we
+      # don't detect tags inside "foo@example.com" or "{@link}".
+      #
+      # Also check that the @tag is not part of an indented code block -
+      # in which case we also ignore the tag.
+      def skip_to_next_at_tag
+        @multiline_tag[:doc] += match(/[^@]+/)
+
+        while look(/@/) && (!prev_char_is_whitespace? || indented_as_code?)
+          @multiline_tag[:doc] += match(/@+[^@]+/)
+        end
+      end
+
+      def prev_char_is_whitespace?
+        @multiline_tag[:doc][-1,1] =~ /\s/
+      end
+
+      def indented_as_code?
+        @multiline_tag[:doc] =~ /^ {4,}[^\n]*\z/
+      end
+    end
+
+  end
+end

data/lib/jsduck/doc/processor.rb

@@ -0,0 +1,52 @@
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Doc
+
+    # Processes @tag data detected from doc-comment, transforming it
+    # into a class/member hash which can be then later further merged
+    # with code hash.
+    #
+    # Its main work is done through calling the #process_doc method of
+    # all the Tag classes that have registered themselves to process a
+    # particular set of @tags through defining a .tagname attribute.
+    class Processor
+      # Allow passing in filename and line for error reporting
+      attr_accessor :filename
+      attr_accessor :linenr
+
+      def initialize
+        @filename = ""
+        @linenr = 0
+      end
+
+      # Given tagname and map of tags from DocParser, produces docs
+      # of the type determined by tagname.
+      def process(tagname, doc_map)
+        hash = {
+          :tagname => tagname,
+          :doc => extract_doc(doc_map),
+        }
+
+        position = {:filename => @filename, :linenr => @linenr}
+
+        doc_map.each_pair do |name, value|
+          if tag = TagRegistry.get_by_name(name)
+            tag.process_doc(hash, value, position)
+          end
+        end
+
+        return hash
+      end
+
+      private
+
+      def extract_doc(doc_map)
+        tag = doc_map[:doc] ? doc_map[:doc].first : {}
+        return tag[:doc] || ""
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/doc/scanner.rb

@@ -0,0 +1,76 @@
+require 'jsduck/doc/standard_tag_parser'
+
+module JsDuck
+  module Doc
+
+    # Abstract base class for parsing doc-comments.
+    #
+    # The methods of this class are to be called from implementations
+    # of concrete @tags.  Although the @tag classes will get passed an
+    # instance of Doc::Parser, only methods of Doc::Scanner should be
+    # called by them.
+    #
+    class Scanner
+      def initialize
+        @ident_pattern = /[$\w-]+/
+        @ident_chain_pattern = /[$\w-]+(\.[$\w-]+)*/
+
+        @input = nil # set to StringScanner in subclass
+      end
+
+      # Provides access to StringScanner
+      attr_reader :input
+
+      # Parses standard pattern common in several builtin tags, which
+      # goes like this:
+      #
+      #     @tag {Type} [some.name=default]
+      #
+      # See StandardTagParser#parse for details.
+      #
+      def standard_tag(cfg)
+        Doc::StandardTagParser.new(self).parse(cfg)
+      end
+
+      # matches chained.identifier.name and returns it
+      def ident_chain
+        @input.scan(@ident_chain_pattern)
+      end
+
+      # matches identifier and returns its name
+      def ident
+        @input.scan(@ident_pattern)
+      end
+
+      # Looks for the existance of pattern.  Returns the matching
+      # string on success, nil on failure, but doesn't advance the
+      # scan pointer.
+      def look(re)
+        @input.check(re)
+      end
+
+      # Matches the given pattern and advances the scan pointer
+      # returning the string that matched.  When the pattern doesn't
+      # match, nil is returned.
+      def match(re)
+        @input.scan(re)
+      end
+
+      # Skips all whitespace.  Moves scan pointer to next non-whitespace
+      # character.
+      def skip_white
+        @input.scan(/\s+/)
+      end
+
+      # Skips horizontal whitespace (tabs and spaces).  Moves scan
+      # pointer to next non-whitespace character or to the end of line.
+      # Returns self to allow chaining.
+      def hw
+        @input.scan(/[ \t]+/)
+        self
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/doc/standard_tag_parser.rb

@@ -0,0 +1,154 @@
+module JsDuck
+  module Doc
+
+    # Helper in parsing the standard tag pattern with type definition
+    # followed by name and default value:
+    #
+    # @tag {Type} [some.name=default]
+    #
+    class StandardTagParser
+      # Initialized with Doc::Scanner instance
+      def initialize(doc_scanner)
+        @ds = doc_scanner
+      end
+
+      # Parses the standard tag pattern.
+      #
+      # Takes as parameter a configuration hash which can contain the
+      # following keys:
+      #
+      # - :tagname => The :tagname of the hash to return.
+      #
+      # - :type => True to parse {Type} section.
+      #            Produces :type and :optional keys.
+      #
+      # - :name => Trye to parse [some.name=default] section.
+      #            Produces :name, :default and :optional keys.
+      #
+      # Returns tag definition hash containing the given :tagname and a
+      # set of other fields depending on whether :type and :name configs
+      # were specified and how their matching succeeded.
+      #
+      def parse(cfg)
+        tag = {:tagname => cfg[:tagname]}
+        add_type(tag) if cfg[:type]
+        add_name_with_default(tag) if cfg[:name]
+        tag
+      end
+
+      private
+
+      # matches {type} if possible and sets it on given tag hash.
+      # Also checks for {optionality=} in type definition.
+      def add_type(tag)
+        if hw.look(/\{/)
+          tdf = typedef
+          tag[:type] = tdf[:type]
+          tag[:optional] = true if tdf[:optional]
+        end
+      end
+
+      # matches {...=} and returns text inside brackets
+      def typedef
+        match(/\{/)
+
+        name = parse_balanced(/\{/, /\}/, /[^{}'"]*/)
+
+        if name =~ /=$/
+          name = name.chop
+          optional = true
+        else
+          optional = nil
+        end
+
+        match(/\}/)
+
+        return {:type => name, :optional => optional}
+      end
+
+      # matches: <ident-chain> | "[" <ident-chain> [ "=" <default-value> ] "]"
+      def add_name_with_default(tag)
+        if hw.match(/\[/)
+          tag[:name] = hw.ident_chain
+          if hw.match(/=/)
+          hw
+          tag[:default] = default_value
+        end
+        hw.match(/\]/)
+          tag[:optional] = true
+        else
+          tag[:name] = hw.ident_chain
+        end
+      end
+
+      # Attempts to allow balanced braces in default value.
+      # When the nested parsing doesn't finish at closing "]",
+      # roll back to beginning and simply grab anything up to closing "]".
+      def default_value
+        start_pos = @ds.input.pos
+        value = parse_balanced(/\[/, /\]/, /[^\[\]'"]*/)
+        if look(/\]/)
+          value
+        else
+          @ds.input.pos = start_pos
+          match(/[^\]]*/)
+        end
+      end
+
+      # Helper method to parse a string up to a closing brace,
+      # balancing opening-closing braces in between.
+      #
+      # @param re_open  The beginning brace regex
+      # @param re_close The closing brace regex
+      # @param re_rest  Regex to match text without any braces and strings
+      def parse_balanced(re_open, re_close, re_rest)
+        result = parse_with_strings(re_rest)
+        while look(re_open)
+          result += match(re_open)
+          result += parse_balanced(re_open, re_close, re_rest)
+          result += match(re_close)
+          result += parse_with_strings(re_rest)
+        end
+        result
+      end
+
+      # Helper for parse_balanced to parse rest of the text between
+      # braces, taking account the strings which might occur there.
+      def parse_with_strings(re_rest)
+        result = match(re_rest)
+        while look(/['"]/)
+          result += parse_string('"') if look(/"/)
+          result += parse_string("'") if look(/'/)
+          result += match(re_rest)
+        end
+        result
+      end
+
+      # Parses "..." or '...' including the escape sequence \' or '\"
+      def parse_string(quote)
+        re_quote = Regexp.new(quote)
+        re_rest = Regexp.new("(?:[^"+quote+"\\\\]|\\\\.)*")
+        match(re_quote) + match(re_rest) + (match(re_quote) || "")
+      end
+
+      ### Forward these calls to Doc::Scanner
+
+      def ident_chain
+        @ds.ident_chain
+      end
+
+      def look(re)
+        @ds.look(re)
+      end
+
+      def match(re)
+        @ds.match(re)
+      end
+
+      def hw
+        @ds.hw
+      end
+    end
+
+  end
+end

data/lib/jsduck/doc/subproperties.rb

@@ -0,0 +1,64 @@
+require 'jsduck/util/singleton'
+require 'jsduck/logger'
+
+module JsDuck
+  module Doc
+
+    # Detects nested structure of subproperties.
+    class Subproperties
+      include Util::Singleton
+
+      # Given array of e.g. @param tags from Doc::Parser with names
+      # containing dots:
+      #
+      #     {:name => "foo"},
+      #     {:name => "foo.bar"},
+      #     {:name => "foo.baz"},
+      #     {:name => "zap"},
+      #
+      # Produces nested structure:
+      #
+      #     {:name => "foo", :properties => [
+      #         {:name => "bar"},
+      #         {:name => "baz"}]},
+      #     {:name => "zap"},
+      #
+      # Secondly it takes a position argument which is used for
+      # logging warnings when bogus subproperty syntax is encountered.
+      def nest(raw_items, pos)
+        # First item can't be namespaced, if it is ignore the rest.
+        if raw_items[0] && raw_items[0][:name] =~ /\./
+          return [raw_items[0]]
+        end
+
+        # build name-index of all items
+        index = {}
+        raw_items.each {|it| index[it[:name]] = it }
+
+        # If item name has no dots, add it directly to items array.
+        # Otherwise look up the parent of item and add it as the
+        # property of that parent.
+        items = []
+        raw_items.each do |it|
+          if it[:name] =~ /^(.+)\.([^.]+)$/
+            it[:name] = $2
+            parent = index[$1]
+            if parent
+              parent[:properties] = [] unless parent[:properties]
+              parent[:properties] << it
+            else
+              msg = "Ignoring subproperty #{$1}.#{$2}, no parent found with name '#{$1}'."
+              Logger.warn(:subproperty, msg, pos[:filename], pos[:linenr])
+            end
+          else
+            items << it
+          end
+        end
+
+        return items
+      end
+
+    end
+
+  end
+end