solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/class_doc_expander.rb

@@ -0,0 +1,132 @@
+require 'jsduck/class'
+
+module JsDuck
+
+  # Expands class docset into one or more docsets.
+  #
+  # The resulting list can contain the following:
+  #
+  # - the base class docset itself (always present)
+  # - configs detected from comment
+  # - constructor detected from comment
+  # - members detected from code
+  #
+  class ClassDocExpander
+
+    # Expands class-docset into multiple docsets.
+    def expand(docset)
+      @constructor_found = false
+
+      expand_comment(docset) + expand_code(docset)
+    end
+
+    private
+
+    # Handles old syntax where configs and constructor are part of class
+    # doc-comment.
+    #
+    # Gathers all tags until first @cfg or @constructor into the first
+    # bare :class group.  We have a special case for @xtype which in
+    # ExtJS comments often appears after @constructor - so we
+    # explicitly place it into :class group.
+    #
+    # Then gathers each @cfg and tags following it into :cfg group, so
+    # that it becomes array of arrays of tags.  This is to allow some
+    # configs to be marked with @private or whatever else.
+    #
+    # Finally gathers tags after @constructor into its group.
+    def expand_comment(docset)
+      groups = {
+        :class => [],
+        :cfg => [],
+        :constructor => [],
+      }
+
+      # By default everything goes to :class group
+      group_name = :class
+
+      docset[:comment].each do |tag|
+        tagname = tag[:tagname]
+
+        if tagname == :cfg || tagname == :constructor
+          group_name = tagname
+          if tagname == :cfg && (tag[:name] !~ /\./ || groups[:cfg].length == 0)
+            groups[:cfg] << []
+          end
+        end
+
+        if tagname == :aliases
+          # For backwards compatibility allow @xtype after @constructor
+          groups[:class] << tag
+        elsif group_name == :cfg
+          groups[:cfg].last << tag
+        else
+          groups[group_name] << tag
+        end
+      end
+
+      groups_to_docsets(groups, docset)
+    end
+
+    # Turns groups hash into list of docsets
+    def groups_to_docsets(groups, docset)
+      results = []
+      results << {
+        :tagname => :class,
+        :type => docset[:type],
+        :comment => groups[:class],
+        :code => docset[:code],
+        :linenr => docset[:linenr],
+      }
+      groups[:cfg].each do |cfg|
+        results << {
+          :tagname => :cfg,
+          :type => docset[:type],
+          :comment => cfg,
+          :code => {},
+          :linenr => docset[:linenr],
+        }
+      end
+      if groups[:constructor].length > 0
+        # Remember that a constructor is already found and ignore if a
+        # constructor is detected from code.
+        @constructor_found = true
+
+        results << {
+          :tagname => :method,
+          :type => docset[:type],
+          :comment => groups[:constructor],
+          :code => {},
+          :linenr => docset[:linenr],
+        }
+      end
+      results
+    end
+
+    # Turns auto-detected class members into docsets in their own
+    # right.
+    def expand_code(docset)
+      results = []
+
+      if docset[:code]
+        (docset[:code][:members] || []).each do |m|
+          results << code_to_docset(m) unless @constructor_found && JsDuck::Class.constructor?(m)
+        end
+      end
+
+      results
+    end
+
+    def code_to_docset(m)
+      return {
+        :tagname => m[:tagname],
+        :type => :no_comment,
+        :comment => [],
+        :code => m,
+        :linenr => m[:linenr],
+      }
+    end
+
+  end
+
+end

data/lib/jsduck/class_name.rb

@@ -0,0 +1,23 @@
+module JsDuck
+
+  # Common routines for manipulating class names.
+  class ClassName
+
+    # Given a full class name extracts the "class"-part of the name.
+    #
+    #     ClassName.short("My.package.Foo") --> "Foo"
+    #
+    # Because we try to emulate ext-doc, it's not as simple as just
+    # taking the last part.  See class_spec.rb for details.
+    def self.short(name)
+      parts = name.split(/\./)
+      short = parts.pop
+      while parts.length > 1 && parts.last =~ /^[A-Z]/
+        short = parts.pop + "." + short
+      end
+      short
+    end
+
+  end
+
+end

data/lib/jsduck/class_writer.rb

@@ -0,0 +1,53 @@
+require 'jsduck/util/parallel'
+require 'jsduck/logger'
+require 'jsduck/util/json'
+require 'jsduck/util/stdout'
+require 'fileutils'
+
+module JsDuck
+
+  # Writes class data into files in JSON or JSONP format or to STDOUT.
+  class ClassWriter
+    def initialize(exporter_class, relations, opts)
+      @relations = relations
+      @exporter = exporter_class.new(relations, opts)
+    end
+
+    # Writes class data into given directory or STDOUT when dir == :stdout.
+    #
+    # Extension is either ".json" for normal JSON output
+    # or ".js" for JsonP output.
+    def write(dir, extension)
+      dir == :stdout ? write_stdout : write_dir(dir, extension)
+    end
+
+    private
+
+    def write_stdout
+      json = Util::Parallel.map(@relations.classes) {|cls| @exporter.export(cls) }.compact
+      Util::Stdout.add(json)
+    end
+
+    def write_dir(dir, extension)
+      FileUtils.mkdir(dir) unless File.exists?(dir)
+
+      Util::Parallel.each(@relations.classes) do |cls|
+        filename = dir + "/" + cls[:name] + extension
+        Logger.log("Writing docs", filename)
+        json = @exporter.export(cls)
+        # skip file if exporter returned nil
+        if json
+          if extension == ".json"
+            Util::Json.write_json(filename, json)
+          elsif extension == ".js"
+            Util::Json.write_jsonp(filename, cls[:name].gsub(/\./, "_"), json)
+          else
+            throw "Unexpected file extension: #{extension}"
+          end
+        end
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/columns.rb

@@ -0,0 +1,56 @@
+module JsDuck
+
+  # Splits array of items with subitems into roughly equal size groups.
+  class Columns
+    # Initialized with the name of subitems field.
+    def initialize(subitems_field)
+      @header_size = 3
+      @subitems_field = subitems_field
+    end
+
+    # Splits the array of items into n chunks so that the sum of
+    # largest chunk is as small as possible.
+    #
+    # This is a brute-force implementation - we just try all the
+    # combinations and choose the best one.
+    def split(items, n)
+      if n == 1
+        [items]
+      elsif items.length <= n
+        Array.new(n) {|i| items[i] ? [items[i]] : [] }
+      else
+        min_max = nil
+        min_arr = nil
+        i = 0
+        while i <= items.length-n
+          i += 1
+          # Try placing 1, 2, 3, ... items to first chunk.
+          # Calculate the remaining chunks recursively.
+          cols = [items[0,i]] + split(items[i, items.length], n-1)
+          max = max_sum(cols)
+          # Is this the optimal solution so far? Remember it.
+          if !min_max || max < min_max
+            min_max = max
+            min_arr = cols
+          end
+        end
+        min_arr
+      end
+    end
+
+    private
+
+    def max_sum(cols)
+      cols.map {|col| sum(col) }.max
+    end
+
+    # Finds the total size of items in array
+    #
+    # The size of one item is it's number of classes + the space for header
+    def sum(arr)
+      arr.reduce(0) {|sum, item| sum + item[@subitems_field].length + @header_size }
+    end
+
+  end
+
+end

data/lib/jsduck/css/parser.rb

@@ -0,0 +1,90 @@
+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 = {})
+        @input = input
+        @docs = []
+      end
+
+      # Returns an array of docsets like the Js::Parser does.
+      def parse
+        root = Sass::Engine.new(@input, :syntax => :scss).to_tree
+        find_doc_comments(root.children)
+        @docs
+      end
+
+      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
+
+        if prev_comment
+          @docs << make_docset(prev_comment)
+        end
+      end
+
+      def make_docset(prev_comment, node=nil)
+        return {
+          :comment => prev_comment.value[0].sub(/\A\/\*\*/, "").sub(/\*\/\z/, ""),
+          :linenr => prev_comment.line,
+          :code => analyze_code(node),
+          :type => :doc_comment,
+        }
+      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
+
+      def build_params(mixin_args)
+        mixin_args.map do |arg|
+          {
+            :name => "$" + arg[0].name,
+            :default => arg[1] ? arg[1].to_sass : nil,
+            :type => arg[1] ? TYPE.detect(arg[1]) : nil,
+          }
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/css/type.rb

@@ -0,0 +1,57 @@
+require 'sass'
+
+module JsDuck
+  module Css
+
+    class Type
+      # Given SASS expression node, determines its type.
+      # When unknown, return nil.
+      def detect(node)
+        if node.class == Sass::Script::Tree::Literal && LITERAL_TYPES[node.value.class]
+          LITERAL_TYPES[node.value.class]
+        elsif node.class == Sass::Script::Funcall && COLOR_FUNCTIONS[node.name]
+          "color"
+        elsif node.class == Sass::Script::Tree::ListLiteral
+          "list"
+        else
+          nil
+        end
+      end
+
+      LITERAL_TYPES = {
+        Sass::Script::Value::Number => "number",
+        Sass::Script::Value::String => "string",
+        Sass::Script::Value::Color => "color",
+        Sass::Script::Value::Bool => "boolean",
+        Sass::Script::Value::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/comment.rb

@@ -0,0 +1,40 @@
+module JsDuck
+  module Doc
+
+    # A simple helper to extract doc comment contents.
+    class Comment
+
+      # Extracts content inside /** ... */
+      def self.purify(input)
+        result = []
+
+        # We can have two types of lines:
+        # - those beginning with *
+        # - and those without it
+        indent = nil
+        input.each_line do |line|
+          line.chomp!
+          if line =~ /\A\s*\*\s?(.*)\z/
+            # When comment contains *-lines, switch indent-trimming off
+            indent = 0
+            result << $1
+          elsif line =~ /\A\s*\z/
+            # pass-through empty lines
+            result << line
+          elsif indent == nil && line =~ /\A(\s*)(.*?\z)/
+            # When indent not measured, measure it and remember
+            indent = $1.length
+            result << $2
+          else
+            # Trim away indent if available
+            result << line.sub(/\A\s{0,#{indent||0}}/, "")
+          end
+        end
+
+        result.join("\n")
+      end
+
+    end
+
+  end
+end