jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/parser.rb

@@ -0,0 +1,76 @@
+require 'jsduck/js/parser'
+require 'jsduck/js/ast'
+require 'jsduck/css/parser'
+require 'jsduck/doc/parser'
+require 'jsduck/doc/processor'
+require 'jsduck/doc/map'
+require 'jsduck/merger'
+require 'jsduck/base_type'
+require 'jsduck/class_doc_expander'
+
+module JsDuck
+  # Performs the actual parsing of CSS or JS source.
+  #
+  # This is the class that brings together all the different steps of
+  # parsing the source.
+  class Parser
+
+    def initialize
+      @doc_parser = Doc::Parser.new
+      @class_doc_expander = ClassDocExpander.new
+      @doc_processor = Doc::Processor.new
+      @merger = Merger.new
+      @filename = ""
+    end
+
+    # Parses file into final docset that can be fed into Aggregator
+    def parse(contents, filename="", options={})
+      @doc_processor.filename = @filename = filename
+
+      parse_js_or_css(contents, filename, options).map do |docset|
+        expand(docset)
+      end.flatten.map do |docset|
+        merge(docset)
+      end
+    end
+
+    private
+
+    # Parses the file depending on filename as JS or CSS
+    def parse_js_or_css(contents, filename, options)
+      if filename =~ /\.s?css$/
+        docs = Css::Parser.new(contents, options).parse
+      else
+        docs = Js::Parser.new(contents, options).parse
+        docs = Js::Ast.new(docs).detect_all!
+      end
+    end
+
+    # Parses the docs, detects tagname and expands class docset
+    def expand(docset)
+      docset[:comment] = @doc_parser.parse(docset[:comment], @filename, docset[:linenr])
+      docset[:doc_map] = Doc::Map.build(docset[:comment])
+      docset[:tagname] = BaseType.detect(docset[:doc_map], docset[:code])
+
+      if docset[:tagname] == :class
+        # expand class into several docsets, and rebuild doc-maps for all of them.
+        @class_doc_expander.expand(docset).map do |ds|
+          ds[:doc_map] = Doc::Map.build(ds[:comment])
+          ds
+        end
+      else
+        docset
+      end
+    end
+
+    # Merges comment and code parts of docset
+    def merge(docset)
+      @doc_processor.linenr = docset[:linenr]
+      docset[:comment] = @doc_processor.process(docset[:tagname], docset[:doc_map])
+      docset.delete(:doc_map)
+
+      @merger.merge(docset, @filename, docset[:linenr])
+    end
+  end
+
+end

data/lib/jsduck/process/accessors.rb

@@ -0,0 +1,133 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    class Accessors
+      def initialize(classes)
+        @classes = classes
+      end
+
+      # Generates accessors in all classes.
+      def process_all!
+        @classes.each_value {|cls| process(cls) }
+      end
+
+      # Given a class, generates accessor methods to configs with
+      # @accessor tag.  Modifies the class by adding these methods.
+      # When class already contains a getter or setter, the method is
+      # not added.
+      def process(cls)
+        # Grab all configs tagged as @accessor
+        accessors = cls[:members].find_all {|m| m[:tagname] == :cfg && m[:accessor] }
+
+        # Build lookup tables of method and event names
+        methods = build_lookup_table(cls[:members], :method)
+        events = build_lookup_table(cls[:members], :event)
+
+        accessors.each do |cfg|
+          # add getter if no method with same name exists
+          get = create_getter(cfg)
+          if !methods[get[:name]]
+            cls[:members] << get
+          end
+          # add setter if no method with same name exists
+          set = create_setter(cfg)
+          if !methods[set[:name]]
+            cls[:members] << set
+          end
+          # for evented accessors
+          if cfg[:evented]
+            # add event if no event with same name exists
+            ev = create_event(cfg)
+            if !events[ev[:name]]
+              cls[:members] << ev
+            end
+          end
+        end
+      end
+
+      def build_lookup_table(members, tagname)
+        map = {}
+        members.each do |m|
+          map[m[:name]] = m if m[:tagname] == tagname
+        end
+        map
+      end
+
+      def create_getter(cfg)
+        name = "get" + upcase_first(cfg[:name])
+        return add_shared({
+            :tagname => :method,
+            :name => name,
+            :doc => "Returns the value of {@link #cfg-#{cfg[:name]}}.",
+            :params => [],
+            :return => {
+              :type => cfg[:type],
+              :doc => "",
+            },
+            :id => "method-" + name,
+          }, cfg)
+      end
+
+      def create_setter(cfg)
+        name = "set" + upcase_first(cfg[:name]);
+        return add_shared({
+            :tagname => :method,
+            :name => name,
+            :doc => "Sets the value of {@link #cfg-#{cfg[:name]}}.",
+            :params => [{
+                :type => cfg[:type],
+                :name => cfg[:name],
+                :doc => "",
+              }],
+            :id => "method-" + name,
+          }, cfg)
+      end
+
+      def create_event(cfg)
+        name = cfg[:name].downcase + "change"
+        setter_name = "set" + upcase_first(cfg[:name]);
+        return add_shared({
+            :tagname => :event,
+            :name => name,
+            :doc => "Fires when the {@link ##{cfg[:id]}} configuration is changed by {@link #method-#{setter_name}}.",
+            :params => [
+              {
+                :name => "this",
+                :type => cfg[:owner],
+                :doc => "The #{cfg[:owner]} instance."
+              },
+              {
+                :name => "value",
+                :type => cfg[:type],
+                :doc => "The new value being set."
+              },
+              {
+                :name => "oldValue",
+                :type => cfg[:type],
+                :doc => "The existing value."
+              },
+            ],
+            :id => "event-" + name,
+          }, cfg)
+      end
+
+      def add_shared(hash, cfg)
+        hash.merge!({
+            :owner => cfg[:owner],
+            :files => cfg[:files],
+            :private => cfg[:private],
+            :protected => cfg[:protected],
+            :autodetected => cfg[:autodetected],
+            :hide => cfg[:hide],
+          })
+      end
+
+      def upcase_first(str)
+        str[0,1].upcase + str[1..-1]
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/circular_deps.rb

@@ -0,0 +1,58 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Checks for circular dependencies
+    class CircularDeps
+      def initialize(classes)
+        @classes = classes
+      end
+
+      # Checks all classes for circular dependencies.
+      #
+      # When found, exits with a fatal error message.
+      def process_all!
+        @classes.each do |cls|
+          if chain = check(cls)
+            Logger.fatal("Class #{cls[:name]} has a circular dependency: #{chain}")
+            exit 1
+          end
+        end
+      end
+
+      # Checks class for circular dependencies.
+      #
+      # When all OK, returns false.
+      #
+      # When circular dependencies found returns a string describing the
+      # problematic dependency chain e.g. "Foo extends Bar mixins Foo".
+      def check(cls, names = [])
+        names += [cls[:name]]
+
+        if cls.parent && chain = track_circular(" extends ", cls.parent, names)
+          return chain
+        end
+
+        cls.mixins.each do |mixin|
+          if chain = track_circular(" mixins ", mixin, names)
+            return chain
+          end
+        end
+
+        false
+      end
+
+      def track_circular(type, cls, names)
+        names += [type]
+        if names.include?(cls[:name])
+          (names + [cls[:name]]).join("")
+        else
+          check(cls, names)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/enums.rb

@@ -0,0 +1,91 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    class Enums
+      def initialize(classes_hash)
+        @classes_hash = classes_hash
+      end
+
+      # Applies additional processing to all enum-classes.
+      def process_all!
+        @classes_hash.each_value do |cls|
+          if cls[:enum]
+            process(cls)
+          end
+        end
+      end
+
+      private
+
+      # processes single class
+      def process(cls)
+        expand_default(cls)
+        reject_not_properties(cls)
+        strip_inheritdoc(cls)
+        cls[:enum][:type] = infer_type(cls) unless cls[:enum][:type]
+      end
+
+      # Expands default value like widget.* into list of properties
+      def expand_default(cls)
+        if cls[:enum][:default] =~ /\A(.*)\.\*\z/
+          each_alias($1) do |name, owner|
+            cls[:members] << {
+              :tagname => :property,
+              :id => 'property-' + name,
+              :name => name,
+              :default => "'" + name + "'",
+              :type => "String",
+              :private => owner[:private],
+              :files => cls[:files],
+              :owner => cls[:name],
+              :doc => "Alias for {@link #{owner[:name]}}.",
+            }
+          end
+        end
+      end
+
+      def each_alias(prefix)
+        @classes_hash.each_value do |cls|
+          if cls[:aliases] && cls[:aliases][prefix]
+            cls[:aliases][prefix].each {|name| yield(name, cls) }
+          end
+        end
+      end
+
+      # Only allow properties as members, throw away all others.
+      def reject_not_properties(cls)
+        cls[:members].reject! do |m|
+          if m[:tagname] == :property
+            false
+          else
+            f = m[:files][0]
+            Logger.warn(:enum, "Enums can only contain properties, #{m[:tagname]} found instead.", f[:filename], f[:linenr])
+            true
+          end
+        end
+      end
+
+      # Remove the auto-inserted inheritdoc tag so the auto-detected enum
+      # values default to being public.
+      def strip_inheritdoc(cls)
+        cls[:members].each do |p|
+          p[:inheritdoc] = nil if p[:autodetected]
+        end
+      end
+
+      # Given an enum class, returns the type infered from its values.
+      def infer_type(cls)
+        if cls[:members].length > 0
+          types = cls[:members].map {|p| p[:type] }
+          types.sort.uniq.join("/")
+        else
+          "Object"
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/ext4_events.rb

@@ -0,0 +1,43 @@
+module JsDuck
+  module Process
+
+    # Appends Ext4 options parameter to the parameter list of each event
+    # in each class.
+    #
+    # But only does so when :ext4_events option is set to true or the
+    # code itself is detected as being writted in Ext4 style.
+    class Ext4Events
+      def initialize(classes, opts={})
+        @classes = classes
+        @opts = opts
+      end
+
+      def process_all!
+        if @opts[:ext4_events] == true || (@opts[:ext4_events] == nil && ext4_style_code?)
+          @classes.each_value {|cls| process(cls) }
+        end
+      end
+
+      # Are we dealing with code looking like ExtJS 4?
+      # True if any of the classes is defined with Ext.define()
+      def ext4_style_code?
+        @classes.values.any? {|cls| cls[:code_type] == :ext_define }
+      end
+
+      def process(cls)
+        cls[:members].each do |m|
+          m[:params] << OPTIONS if m[:tagname] == :event
+        end
+      end
+
+      OPTIONS = {
+        :tagname => :params,
+        :name => "eOpts",
+        :type => "Object",
+        :doc => "The options object passed to {@link Ext.util.Observable#addListener}."
+      }
+
+    end
+
+  end
+end

data/lib/jsduck/process/global_members.rb

@@ -0,0 +1,36 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Prints warning for each global member.
+    # Removes "global" class when --ignore-global option used.
+    # Warnings for global members are printed regardless of that setting,
+    # but of course can be turned off using --warnings=-global
+    class GlobalMembers
+      def initialize(classes_hash, opts)
+        @classes_hash = classes_hash
+        @opts = opts
+      end
+
+      def process_all!
+        # Do nothing when there's no "global" class.
+        return unless @classes_hash["global"]
+
+        # Warnings for each global member
+        @classes_hash["global"][:members].each do |m|
+          type = m[:tagname].to_s
+          name = m[:name]
+          file = m[:files][0]
+          Logger.warn(:global, "Global #{type}: #{name}", file[:filename], file[:linenr])
+        end
+
+        # Throw away the "global" class when --ignore-global option used
+        if @opts.ignore_global
+          @classes_hash.delete("global")
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/ignored_classes.rb

@@ -0,0 +1,16 @@
+module JsDuck
+  module Process
+
+    # Gets rid of classes marked with @ignore
+    class IgnoredClasses
+      def initialize(classes_hash)
+        @classes_hash = classes_hash
+      end
+
+      def process_all!
+        @classes_hash.delete_if {|name, cls| cls[:ignore] }
+      end
+    end
+
+  end
+end