jsduck 3.0.1 → 3.1.0

data/lib/jsduck/app_data.rb

@@ -0,0 +1,34 @@
+require 'jsduck/json_duck'
+require 'jsduck/icons'
+require 'jsduck/search_data'
+require 'jsduck/stats'
+
+module JsDuck
+
+  # Creates big JS file with data for Docs app.
+  class AppData
+    attr_accessor :guides
+    attr_accessor :videos
+    attr_accessor :examples
+
+    def initialize(relations, opts)
+      @relations = relations
+      @opts = opts
+    end
+
+    # Writes classes, guides, videos, and search data to one big .js file
+    def write(filename)
+      js = "Docs.data = " + JsonDuck.generate({
+        :classes => Icons.new.create(@relations.classes),
+        :guides => @guides.to_array,
+        :videos => @videos.to_array,
+        :examples => @examples.to_array,
+        :search => SearchData.new.create(@relations.classes),
+        :stats => @opts.stats ? Stats.new.create(@relations.classes) : [],
+      }) + ";\n"
+      File.open(filename, 'w') {|f| f.write(js) }
+    end
+
+  end
+
+end

data/lib/jsduck/{exporter.rb → app_exporter.rb}

@@ -1,29 +1,31 @@
+require 'jsduck/full_exporter'
+require 'jsduck/renderer'
+require 'jsduck/doc_formatter'
+
 module JsDuck
 
-  # Export class data as hash with :cfg being replace with :cfgs and
-  # including all the inherited members too.  Same for :properties,
-  # :methods, and :events.
-  class Exporter
-    def initialize(relations)
-      @relations = relations
+  # Exports data for Docs app.
+  class AppExporter < FullExporter
+    def initialize(relations, opts)
+      super(relations, opts)
+
+      @renderer = Renderer.new
+      # Inject formatter to all meta-tags.
+      doc_formatter = DocFormatter.new(relations, opts)
+      opts.meta_tags.each {|tag| tag.formatter = doc_formatter }
+      @renderer.meta_tags = opts.meta_tags
     end
 
-    # Returns all data in Class object as hash.
+    # Returns compacted class data hash which contains an additional
+    # :html field with full HTML to show on class overview page.
     def export(cls)
-      h = cls.to_hash
-      h[:members] = {}
-      Class.default_members_hash.each_key do |key|
-        h[:members][key] = cls.members(key)
-        h[:statics][key] = cls.members(key, :statics)
-      end
-      h[:component] = cls.inherits_from?("Ext.Component")
-      h[:superclasses] = cls.superclasses.collect {|c| c.full_name }
-      h[:subclasses] = @relations.subclasses(cls).collect {|c| c.full_name }
-      h[:mixedInto] = @relations.mixed_into(cls).collect {|c| c.full_name }
-      h[:allMixins] = cls.all_mixins.collect {|c| c.full_name }
-      h
+      data = super(cls)
+      data[:html] = @renderer.render(data)
+      return compact(data)
     end
 
+    private
+
     # removes extra data from export
     def compact(cls)
       cls.delete(:doc)

data/lib/jsduck/categories.rb

@@ -1,81 +1,32 @@
 require 'jsduck/logger'
 require 'jsduck/json_duck'
+require 'jsduck/file_categories'
 require 'jsduck/auto_categories'
 
 module JsDuck
 
   # Reads in categories and outputs them as HTML div
   class Categories
-    def initialize(doc_formatter, relations={})
-      @doc_formatter = doc_formatter
-      @relations = relations
-      @categories = []
-    end
-
-    # Automatically divides all available classes into categories
-    def auto_generate
-      @categories = AutoCategories.new(@relations).generate
-    end
-
-    # Parses categories in JSON file
-    def parse(path)
-      @categories = JsonDuck.read(path)
-
-      # Don't crash if old syntax is used.
-      if @categories.is_a?(Hash) && @categories["categories"]
-        Logger.instance.warn('Update categories file to contain just the array inside {"categories": [...]}')
-        @categories = @categories["categories"]
-      end
-
-      # Perform expansion on all class names containing * wildcard
-      @categories.each do |cat|
-        cat["groups"].each do |group|
-          group["classes"] = group["classes"].map do |name|
-            expand(name) # name =~ /\*/ ? expand(name) : name
-          end.flatten
-        end
-      end
-
-      validate
-    end
-
-    # Expands class name like 'Foo.*' into multiple class names.
-    def expand(name)
-      re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
-      classes = @relations.to_a.find_all {|cls| re =~ cls[:name] && !cls[:private] }.map {|cls| cls[:name] }.sort
-      if classes.length == 0
-        Logger.instance.warn("No class found matching a pattern '#{name}' in categories file.")
+    def self.create(filename, doc_formatter, relations)
+      if filename
+        categories = FileCategories.new(filename, relations)
+      else
+        categories = AutoCategories.new(relations)
       end
-      classes
+      Categories.new(categories.generate, doc_formatter, relations)
     end
 
-    # Prints warnings for missing classes in categories file
-    def validate
-      # Build a map of all classes listed in categories
-      listed_classes = {}
-      @categories.each do |cat|
-        cat["groups"].each do |group|
-          group["classes"].each do |cls_name|
-            listed_classes[cls_name] = true
-          end
-        end
-      end
-
-      # Check that each existing non-private class is listed
-      @relations.each do |cls|
-        unless listed_classes[cls[:name]] || cls[:private]
-          Logger.instance.warn("Class '#{cls[:name]}' not found in categories file")
-        end
-      end
+    def initialize(categories, doc_formatter, relations={})
+      @categories = categories
+      @doc_formatter = doc_formatter
+      @relations = relations
     end
 
     # Returns HTML listing of classes divided into categories
     def to_html
-      return "" if @categories.length == 0
-
       html = @categories.map do |category|
         [
-          "<div class='section classes'>",
+          "<div class='section'>",
           "<h1>#{category['name']}</h1>",
           render_columns(category['groups']),
           "<div style='clear:both'></div>",
@@ -91,7 +42,7 @@ module JsDuck
     end
 
     def render_columns(groups)
-      align = ["lft", "mid", "rgt"]
+      align = ["left-column", "middle-column", "right-column"]
       i = -1
       return split(groups, 3).map do |col|
         i += 1

data/lib/jsduck/class.rb

@@ -62,7 +62,7 @@ module JsDuck
         @relations[classname]
       elsif !@relations.ignore?(classname)
         context = @doc[:files][0]
-        Logger.instance.warn("Class #{classname} not found", context[:filename], context[:linenr])
+        Logger.instance.warn(:extend, "Class #{classname} not found", context[:filename], context[:linenr])
         nil
       end
     end
@@ -89,7 +89,8 @@ module JsDuck
     #
     # See members_hash for details.
     def members(type, context=:members)
-      ms = members_hash(type, context).values.sort {|a,b| a[:name] <=> b[:name] }
+      ms = members_hash(type, context).values.find_all {|m| !m[:private] }
+      ms.sort! {|a,b| a[:name] <=> b[:name] }
       type == :method ? constructor_first(ms) : ms
     end
 
@@ -104,7 +105,7 @@ module JsDuck
       ms
     end
 
-    # Returns hash of public members of class (and of parent classes
+    # Returns hash of all members in class (and of parent classes
     # and mixin classes).  Members are methods, properties, cfgs,
     # events (member type is specified through 'type' parameter).
     #
@@ -115,7 +116,7 @@ module JsDuck
       if @doc[:singleton] && context == :statics
         # Warn if singleton has static members
         if @doc[context][type].length > 0
-          Logger.instance.warn("Singleton class #{@doc[:name]} can't have static members, remove the @static tag.")
+          Logger.instance.warn(:sing_static, "Singleton class #{@doc[:name]} can't have static members, remove the @static tag.")
         end
         return {}
       end
@@ -148,7 +149,7 @@ module JsDuck
     def local_members_hash(type, context)
       local_members = {}
       (@doc[context][type] || []).each do |m|
-        local_members[m[:name]] = m if !m[:private]
+        local_members[m[:name]] = m
       end
       local_members
     end
@@ -174,13 +175,26 @@ module JsDuck
       @members_map[type_name ? "#{type_name}-#{name}" : name]
     end
 
-    # Loops through each member of the class, invoking block with each of them
-    def each_member(&block)
+    # Returns all public members of class, including the inherited and mixed in ones
+    def all_members
+      all = []
       [:members, :statics].each do |group|
-        @doc[group].each_value do |members|
-          members.each(&block)
+        @doc[group].each_key do |type|
+          all += members(type, group)
         end
       end
+      all
+    end
+
+    # Returns all local public members of class
+    def all_local_members
+      all = []
+      [:members, :statics].each do |group|
+        @doc[group].each_value do |ms|
+          all += ms.find_all {|m| !m[:private] }
+        end
+      end
+      all
     end
 
     # A way to access full class name with similar syntax to

data/lib/jsduck/class_formatter.rb

@@ -69,9 +69,9 @@ module JsDuck
       else
         context = @formatter.doc_context
         if tp.error == :syntax
-          Logger.instance.warn("Incorrect type syntax #{type}", context[:filename], context[:linenr])
+          Logger.instance.warn(:type_syntax, "Incorrect type syntax #{type}", context[:filename], context[:linenr])
         else
-          Logger.instance.warn("Unknown type #{type}", context[:filename], context[:linenr])
+          Logger.instance.warn(:type_name, "Unknown type #{type}", context[:filename], context[:linenr])
         end
         type
       end

data/lib/jsduck/class_writer.rb

@@ -0,0 +1,49 @@
+require 'jsduck/parallel_wrap'
+require 'jsduck/logger'
+require 'jsduck/json_duck'
+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)
+      @parallel = ParallelWrap.new(:in_processes => opts.processes)
+    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 = @parallel.map(@relations.classes) {|cls| @exporter.export(cls) }
+      puts JsonDuck.generate(json)
+    end
+
+    def write_dir(dir, extension)
+      FileUtils.mkdir(dir)
+      @parallel.each(@relations.classes) do |cls|
+        filename = dir + "/" + cls[:name] + extension
+        Logger.instance.log("Writing docs", filename)
+        json = @exporter.export(cls)
+        if extension == ".json"
+          JsonDuck.write_json(filename, json)
+        elsif extension == ".js"
+          JsonDuck.write_jsonp(filename, cls[:name].gsub(/\./, "_"), json)
+        else
+          throw "Unexpected file extension: #{extension}"
+        end
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/doc_formatter.rb

@@ -55,14 +55,14 @@ module JsDuck
     # name actually exists.
     attr_accessor :relations
 
-    def initialize
+    def initialize(relations={}, opts={})
       @class_context = ""
       @doc_context = {}
       @max_length = 120
-      @relations = {}
+      @relations = relations
       @images = []
-      @link_tpl = '<a href="%c%#%m">%a</a>'
-      @img_tpl = '<img src="%u" alt="%a"/>'
+      @link_tpl = opts[:link_tpl] || '<a href="%c%#%m">%a</a>'
+      @img_tpl = opts[:img_tpl] || '<img src="%u" alt="%a"/>'
       @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
       @img_re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
       @example_annotation_re = /<pre><code>\s*@example( +[^\n]*)?\s+/m
@@ -130,10 +130,13 @@ module JsDuck
         file = @doc_context[:filename]
         line = @doc_context[:linenr]
         if !@relations[cls]
-          Logger.instance.warn("#{input} links to non-existing class", file, line)
+          Logger.instance.warn(:link, "#{input} links to non-existing class", file, line)
           text
         elsif member && !get_member(cls, member, type)
-          Logger.instance.warn("#{input} links to non-existing member", file, line)
+          Logger.instance.warn(:link, "#{input} links to non-existing member", file, line)
+          text
+        elsif member && !public_member?(cls, member, type)
+          Logger.instance.warn(:link, "#{input} links to private member", file, line)
           text
         else
           link(cls, member, text, type)
@@ -153,7 +156,7 @@ module JsDuck
         member = $4
         after = $5
 
-        if @relations[cls] && (member ? get_member(cls, member) : cls =~ /\./)
+        if @relations[cls] && (member ? public_member?(cls, member) : cls =~ /\./)
           label = member ? cls+"."+member : cls
           before + link(cls, member, label) + after
         else
@@ -202,8 +205,13 @@ module JsDuck
       end
     end
 
+    def public_member?(cls, member, type=nil)
+      m = get_member(cls, member, type)
+      return m && !m[:private]
+    end
+
     def get_member(cls, member, type=nil)
-      @relations[cls] && @relations[cls].get_member(member, type)
+      return @relations[cls] && @relations[cls].get_member(member, type)
     end
 
     # Formats doc-comment for placement into HTML.

data/lib/jsduck/doc_parser.rb

@@ -93,9 +93,13 @@ module JsDuck
         elsif look(/@extends?\b/)
           at_extends
         elsif look(/@mixins?\b/)
-          at_mixins
+          class_list_at_tag(/@mixins?/, :mixins)
         elsif look(/@alternateClassNames?\b/)
-          at_alternateClassName
+          class_list_at_tag(/@alternateClassNames?/, :alternateClassNames)
+        elsif look(/@uses\b/)
+          class_list_at_tag(/@uses/, :uses)
+        elsif look(/@requires\b/)
+          class_list_at_tag(/@requires/, :requires)
         elsif look(/@singleton\b/)
           boolean_at_tag(/@singleton/, :singleton)
         elsif look(/@event\b/)
@@ -115,12 +119,20 @@ module JsDuck
         elsif look(/@type\b/)
           at_type
         elsif look(/@xtype\b/)
-          at_xtype
+          at_xtype(/@xtype/, "widget")
         elsif look(/@ftype\b/)
-          at_ftype
+          at_xtype(/@ftype/, "feature")
+        elsif look(/@ptype\b/)
+          at_xtype(/@ptype/, "plugin")
         elsif look(/@member\b/)
           at_member
-        elsif look(/@alias\b/)
+        elsif look(/@inherit[dD]oc\b/)
+          at_inheritdoc
+        elsif look(/@alias\s+[\w.]+#\w+/)
+          # For backwards compatibility.
+          # @alias tag was used as @inheritdoc before
+          at_inheritdoc
+        elsif look(/@alias/)
           at_alias
         elsif look(/@deprecated\b/)
           at_deprecated
@@ -194,21 +206,12 @@ module JsDuck
       skip_white
     end
 
-    # matches @mixins name1 name2 ...
-    def at_mixins
-      match(/@mixins?/)
-      add_tag(:mixins)
-      skip_horiz_white
-      @current_tag[:mixins] = class_list
-      skip_white
-    end
-
-    # matches @alternateClassName name1 name2 ...
-    def at_alternateClassName
-      match(/@alternateClassNames?/)
-      add_tag(:alternateClassNames)
+    # matches @<tagname> classname1 classname2 ...
+    def class_list_at_tag(regex, tagname)
+      match(regex)
+      add_tag(tagname)
       skip_horiz_white
-      @current_tag[:alternateClassNames] = class_list
+      @current_tag[tagname] = class_list
       skip_white
     end
 
@@ -302,22 +305,6 @@ module JsDuck
       skip_white
     end
 
-    # matches @xtype name
-    def at_xtype
-      match(/@xtype/)
-      add_tag(:xtype)
-      maybe_ident_chain(:name)
-      skip_white
-    end
-
-    # matches @ftype name
-    def at_ftype
-      match(/@ftype/)
-      add_tag(:ftype)
-      maybe_ident_chain(:name)
-      skip_white
-    end
-
     # matches @member name ...
     def at_member
       match(/@member/)
@@ -326,11 +313,30 @@ module JsDuck
       skip_white
     end
 
-    # matches @alias class.name#type-member
+    # matches @xtype/ptype/ftype/... name
+    def at_xtype(tag, namespace)
+      match(tag)
+      add_tag(:alias)
+      skip_horiz_white
+      @current_tag[:name] = namespace + "." + (ident_chain || "")
+      skip_white
+    end
+
+    # matches @alias <ident-chain>
     def at_alias
       match(/@alias/)
       add_tag(:alias)
       skip_horiz_white
+      @current_tag[:name] = ident_chain
+      skip_white
+    end
+
+    # matches @inheritdoc class.name#type-member
+    def at_inheritdoc
+      match(/@inherit[dD]oc|@alias/)
+
+      add_tag(:inheritdoc)
+      skip_horiz_white
       if look(@ident_chain_pattern)
         @current_tag[:cls] = ident_chain
         if look(/#\w/)