jsduck 5.3.4 → 6.0.0beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 08d1a9118d609f1035882ef597e139b4de6655a8
-  data.tar.gz: 06595bf58bd8c1382dea7e3e01155909ed8c9e69
+  metadata.gz: 22b2eee9a27379a8bcb0c152fd6749ac45803aae
+  data.tar.gz: 19aca3cbd478c9b9c9dd917a50950580d461ad3c
 SHA512:
-  metadata.gz: 6099cee44749de6f4070a0f8b3127f1aad85e1cca3f043e5096afeda5016461d494eb07a82efbda85b2d11be2b1a7de8d8f0cd20a6ffe62e125dcef8df329fcb
-  data.tar.gz: db32d24569d9ed089ae9a5da09137b780e14c0d6ae15146ede2df077f30ba7ef6700505f72531e07e064a0de9bffcf18c101e3f50bcb093ff3a8b2189118bb4e
+  metadata.gz: 18f5f78668b4d1ccc721ab6e0c6fc4e2b07716a524269d6d87bbca2d02b87505e46cbc4f5e27e0c54f451bd40266bf09bbc60f7c9322033a732b9bf6797d0b0a
+  data.tar.gz: 8d73b981ebc7e1edaadb280b5bd59293ecdb91d54aa98be139c63f53286a8ca7cbcfaa1694e586efa624371cc03edd7d99c2f77f6c984976a23312205574eeb7

data/README.md

@@ -98,7 +98,7 @@ Who's using JSDuck?
 - [CKEditor](http://docs.ckeditor.com)
 - [GeoExt 2](https://github.com/geoext/geoext2)
 - Rally Software [Rally App SDK](https://prod.help.rallydev.com/apps/2.0rc1/doc/)
-- Wikimedia Foundation [Mediawiki](https://doc.wikimedia.org/mediawiki-core/master/js/)
+- Wikimedia Foundation [MediaWiki](https://doc.wikimedia.org/mediawiki-core/master/js/)
   and [VisualEditor](https://doc.wikimedia.org/VisualEditor/master/)
 - [Sencha](http://docs.sencha.com) - obviously :)
 
@@ -148,7 +148,7 @@ input.
 Changelog
 ---------
 
-See [the Releases page](https://github.com/senchalabs/jsduck/Releases).
+See [the Releases page](https://github.com/senchalabs/jsduck/releases).
 
 
 More questions?

data/bin/jsduck

@@ -18,10 +18,10 @@
 $:.unshift File.dirname(File.dirname(__FILE__)) + "/lib"
 
 require 'jsduck/app'
-require 'jsduck/options'
+require 'jsduck/options/processor'
+
+opts = JsDuck::Options::Processor.process(ARGV)
 
-opts = JsDuck::Options.new
-opts.parse!(ARGV)
 exit_code = JsDuck::App.new(opts).run
 
 exit exit_code

data/lib/jsduck/app.rb

@@ -10,7 +10,7 @@ module JsDuck
 
   # The main application logic of jsduck
   class App
-    # Initializes app with JsDuck::Options object
+    # Initializes app with JsDuck::OptionsRecord object
     def initialize(opts)
       @opts = opts
     end

data/lib/jsduck/assets.rb

@@ -36,7 +36,7 @@ module JsDuck
       @guides = Guides.create(@opts.guides, doc_formatter, @opts)
       @videos = Videos.create(@opts.videos)
       @examples = Examples.create(@opts.examples, @opts)
-      @categories = Categories::Factory.create(@opts.categories_path, doc_formatter, @relations)
+      @categories = Categories::Factory.create(@opts.categories, doc_formatter, @relations)
       @news = News.create(@relations, doc_formatter, @opts)
     end
 
@@ -45,8 +45,8 @@ module JsDuck
     #
     # Welcome page and categories are written in JsDuck::IndexHtml
     def write
-      @guides.write(@opts.output_dir+"/guides")
-      Img::Writer.copy(@images.all_used, @opts.output_dir+"/images")
+      @guides.write(@opts.output+"/guides")
+      Img::Writer.copy(@images.all_used, @opts.output+"/images")
     end
 
   end

data/lib/jsduck/base_type.rb

@@ -1,4 +1,4 @@
-require 'jsduck/tag_registry'
+require 'jsduck/member_registry'
 
 module JsDuck
 
@@ -38,7 +38,7 @@ module JsDuck
     # Returns the detected member type on success.
     # Otherwise nil.
     def self.detect_member(doc_map)
-      type = TagRegistry.member_type_names.find {|type| doc_map[type] }
+      type = MemberRegistry.names.find {|type| doc_map[type] }
 
       if type == :cfg
         # Only detect a single @cfg as a :cfg.

data/lib/jsduck/batch_processor.rb

@@ -13,6 +13,7 @@ require 'jsduck/process/inherit_doc'
 require 'jsduck/process/versions'
 require 'jsduck/process/return_values'
 require 'jsduck/process/fires'
+require 'jsduck/process/components'
 require 'jsduck/process/lint'
 require 'jsduck/process/no_doc'
 require 'jsduck/process/circular_deps'
@@ -61,7 +62,7 @@ module JsDuck
     # classes inside Relations container.
     def to_class_objects(docs, opts)
       classes = docs.map {|d| Class.new(d) }
-      Relations.new(classes, opts.external_classes)
+      Relations.new(classes, opts.external)
     end
 
     # Do all kinds of post-processing on Relations object.
@@ -71,6 +72,7 @@ module JsDuck
       Process::Versions.new(relations, opts).process_all!
       Process::ReturnValues.new(relations).process_all!
       Process::Fires.new(relations).process_all!
+      Process::Components.new(relations).process_all!
       Process::Lint.new(relations).process_all!
       Process::NoDoc.new(relations).process_all!
       relations

data/lib/jsduck/categories/file.rb

@@ -38,7 +38,7 @@ module JsDuck
         end.map {|cls| cls[:name] }.sort
 
         if classes.length == 0
-          Logger.warn(:cat_no_match, "No class found matching a pattern '#{name}' in categories file", @filename)
+          Logger.warn(:cat_no_match, "No class found matching a pattern '#{name}' in categories file", {:filename => @filename})
         end
         classes
       end
@@ -58,7 +58,7 @@ module JsDuck
         # Check that each existing non-private & non-deprecated class is listed
         @relations.each do |cls|
           unless listed_classes[cls[:name]] || cls[:private] || cls[:deprecated]
-            Logger.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file", @filename)
+            Logger.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file", {:filename => @filename})
           end
         end
       end

data/lib/jsduck/class_doc_expander.rb

@@ -50,7 +50,7 @@ module JsDuck
 
         if tagname == :cfg || tagname == :constructor
           group_name = tagname
-          if tagname == :cfg && tag[:name] !~ /\./
+          if tagname == :cfg && (tag[:name] !~ /\./ || groups[:cfg].length == 0)
             groups[:cfg] << []
           end
         end

data/lib/jsduck/css/parser.rb

@@ -1,120 +1,89 @@
-require 'jsduck/css/lexer'
+require 'sass'
+require 'jsduck/css/type'
 
 module JsDuck
   module Css
 
+    # Parses SCSS using the official SASS parser.
     class Parser
+      TYPE = Css::Type.new
+
       def initialize(input, options = {})
-        @lex = Css::Lexer.new(input)
+        @input = input
         @docs = []
       end
 
-      # Parses the whole CSS block and returns same kind of structure
-      # that JavaScript parser does.
+      # Returns an array of docsets like the Js::Parser does.
       def parse
-        while !@lex.empty? do
-          if look(:doc_comment)
-            comment = @lex.next(true)
-            @docs << {
-              :comment => comment[:value],
-              :linenr => comment[:linenr],
-              :code => code_block,
-              :type => :doc_comment,
-            }
-          else
-            @lex.next
-          end
-        end
+        root = Sass::Engine.new(@input, :syntax => :scss).to_tree
+        find_doc_comments(root.children)
         @docs
       end
 
-      # <code-block> := <mixin-declaration> | <var-declaration> | <property>
-      def code_block
-        if look("@mixin")
-          mixin_declaration
-        elsif look(:var, ":")
-          var_declaration
-        else
-          # Default to property like in Js::Parser.
-          {:tagname => :property}
+      private
+
+      def find_doc_comments(nodes)
+        prev_comment = nil
+
+        nodes.each do |node|
+          if prev_comment
+            @docs << make_docset(prev_comment, node)
+            prev_comment = nil
+          end
+
+          if node.class == Sass::Tree::CommentNode
+            if node.type == :normal && node.value[0] =~ /\A\/\*\*/
+              prev_comment = node
+            end
+          end
+
+          find_doc_comments(node.children)
         end
-      end
 
-      # <mixin-declaration> := "@mixin" <ident>
-      def mixin_declaration
-        match("@mixin")
-        return {
-          :tagname => :css_mixin,
-          :name => look(:ident) ? match(:ident) : nil,
-        }
+        if prev_comment
+          @docs << make_docset(prev_comment)
+        end
       end
 
-      # <var-declaration> := <var> ":" <css-value>
-      def var_declaration
-        name = match(:var)
-        match(":")
-        value_list = css_value
+      def make_docset(prev_comment, node=nil)
         return {
-          :tagname => :css_var,
-          :name => name,
-          :default => value_list.map {|v| v[:value] }.join(" "),
-          :type => value_type(value_list),
+          :comment => prev_comment.value[0].sub(/\A\/\*\*/, "").sub(/\*\/\z/, ""),
+          :linenr => prev_comment.line,
+          :code => analyze_code(node),
+          :type => :doc_comment,
         }
       end
 
-      # <css-value> := ...anything up to... [ ";" | "}" | "!default" ]
-      def css_value
-        val = []
-        while !look(";") && !look("}") && !look("!", "default")
-          val << @lex.next(true)
-        end
-        val
-      end
-
-      # Determines type of CSS value
-      def value_type(val)
-        case val[0][:type]
-        when :number
-          "number"
-        when :dimension
-          "length"
-        when :percentage
-          "percentage"
-        when :string
-          "string"
-        when :hash
-          "color"
-        when :ident
-          case val[0][:value]
-          when "true", "false"
-            return "boolean"
-          when "rgb", "rgba", "hsl", "hsla"
-            return "color"
-          when "black", "silver", "gray", "white", "maroon",
-            "red", "purple", "fuchsia", "green", "lime", "olive",
-            "yellow", "navy", "blue", "teal", "aqua", "orange"
-            return "color"
-          when "transparent"
-            return "color"
-          end
+      def analyze_code(node)
+        if node.class == Sass::Tree::VariableNode
+          return {
+            :tagname => :css_var,
+            :name => "$" + node.name,
+            :default => node.expr.to_sass,
+            :type => TYPE.detect(node.expr),
+          }
+        elsif node.class == Sass::Tree::MixinDefNode
+          return {
+            :tagname => :css_mixin,
+            :name => node.name,
+            :params => build_params(node.args),
+          }
+        else
+          # Default to property like in Js::Parser.
+          return {:tagname => :property}
         end
       end
 
-      # Matches all arguments, returns the value of last match
-      # When the whole sequence doesn't match, throws exception
-      def match(*args)
-        if look(*args)
-          last = nil
-          args.length.times { last = @lex.next }
-          last
-        else
-          throw "Expected: " + args.join(", ")
+      def build_params(mixin_args)
+        mixin_args.map do |arg|
+          {
+            :name => "$" + arg[0].name,
+            :default => arg[1] ? arg[1].to_s : nil,
+            :type => arg[1] ? TYPE.detect(arg[1]) : nil,
+          }
         end
       end
 
-      def look(*args)
-        @lex.look(*args)
-      end
     end
 
   end

data/lib/jsduck/css/type.rb

@@ -0,0 +1,55 @@
+require 'sass'
+
+module JsDuck
+  module Css
+
+    class Type
+      # Given SASS expression node, determines its type.
+      # When unknown, return nil.
+      def detect(node)
+        if LITERAL_TYPES[node.class]
+          LITERAL_TYPES[node.class]
+        elsif node.class == Sass::Script::Funcall && COLOR_FUNCTIONS[node.name]
+          "color"
+        else
+          nil
+        end
+      end
+
+      LITERAL_TYPES = {
+        Sass::Script::Number => "number",
+        Sass::Script::String => "string",
+        Sass::Script::Color => "color",
+        Sass::Script::Bool => "boolean",
+        Sass::Script::List => "list",
+      }
+
+      COLOR_FUNCTIONS = {
+        # CSS3 builtins
+        "rgb" => true,
+        "rgba" => true,
+        "hsl" => true,
+        "hsla" => true,
+        # SASS builtins
+        "mix" => true,
+        "adjust-hue" => true,
+        "lighten" => true,
+        "darken" => true,
+        "saturate" => true,
+        "desaturate" => true,
+        "grayscale" => true,
+        "complement" => true,
+        "invert" => true,
+        "opacify" => true,
+        "fade-in" => true,
+        "transparentize" => true,
+        "fade-out" => true,
+        "adjust-color" => true,
+        "scale-color" => true,
+        "change-color" => true,
+      }
+
+    end
+
+  end
+end

data/lib/jsduck/doc/parser.rb

@@ -102,7 +102,7 @@ module JsDuck
 
           skip_white
         else
-          warn(:tag, "Unsupported tag: @#{name}")
+          warn(:tag, "Unsupported tag: @#{name}", [name.to_sym])
           @multiline_tag[:doc] += "@"
         end
       end

data/lib/jsduck/doc/scanner.rb

@@ -73,8 +73,8 @@ module JsDuck
       end
 
       # Prints a warning message
-      def warn(type, msg)
-        Logger.warn(type, msg, @position)
+      def warn(type, msg, params=[])
+        Logger.warn(type, msg, @position, params)
       end
 
     end

data/lib/jsduck/doc/subproperties.rb

@@ -61,7 +61,7 @@ module JsDuck
 
       def warn(name, pos)
         parent = name.sub(/\.[^.]*$/, '')
-        msg = "Ignoring subproperty '#{name}' not parent found with name '#{parent}'."
+        msg = "Ignoring subproperty '#{name}' no parent found with name '#{parent}'."
         Logger.warn(:subproperty, msg, pos)
       end
 

data/lib/jsduck/export_writer.rb

@@ -20,19 +20,19 @@ module JsDuck
     def write
       format_classes
 
-      clean_output_dir unless @opts.output_dir == :stdout
+      clean_output_dir unless @opts.output == :stdout
 
       export_classes
       export_examples_in_guides if @opts.export == :examples
 
-      Util::Stdout.flush if @opts.output_dir == :stdout
+      Util::Stdout.flush if @opts.output == :stdout
     end
 
     private
 
     def export_classes
       cw = ClassWriter.new(get_exporter, @relations, @opts)
-      cw.write(@opts.output_dir, ".json")
+      cw.write(@opts.output, ".json")
     end
 
     def get_exporter
@@ -45,7 +45,7 @@ module JsDuck
 
     def export_examples_in_guides
       gw = GuideWriter.new(Exporter::Examples, @assets.guides, @opts)
-      gw.write(@opts.output_dir, ".json")
+      gw.write(@opts.output, ".json")
     end
 
     # -- util routines --

data/lib/jsduck/exporter/app.rb

@@ -1,6 +1,7 @@
 require 'jsduck/render/class'
 require 'jsduck/exporter/full'
 require 'jsduck/tag_registry'
+require 'jsduck/web/class_icons'
 
 module JsDuck
   module Exporter
@@ -18,7 +19,7 @@ module JsDuck
       def export(cls)
         data = @full_exporter.export(cls)
 
-        data[:component] = cls.inherits_from?("Ext.Component")
+        data[:classIcon] = Web::ClassIcons.get(cls)
         data[:superclasses] = cls.superclasses.collect {|c| c[:name] }
         data[:subclasses] = @relations.subclasses(cls).collect {|c| c[:name] }.sort
         data[:mixedInto] = @relations.mixed_into(cls).collect {|c| c[:name] }.sort