jsduck 3.5.0 → 3.6.0

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.5"
 
   s.name = 'jsduck'
-  s.version = '3.5.0'
-  s.date = '2012-02-15'
+  s.version = '3.6.0'
+  s.date = '2012-02-20'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"

data/lib/jsduck/aggregator.rb

@@ -118,6 +118,9 @@ module JsDuck
     # Items without @member belong by default to the preceding class.
     # When no class precedes them - they too are orphaned.
     def add_member(node)
+      # Completely ignore member if @ignore used
+      return if node[:meta][:ignore]
+
       if node[:owner]
         if @classes[node[:owner]]
           add_to_class(@classes[node[:owner]], node)
@@ -191,6 +194,16 @@ module JsDuck
       })
     end
 
+    # Gets rid of classes marked with @ignore
+    def remove_ignored_classes
+      @documentation.delete_if do |cls|
+        if cls[:meta][:ignore]
+          @classes.delete(cls["name"])
+          true
+        end
+      end
+    end
+
     # Appends Ext4 options parameter to each event parameter list.
     # But only when we are dealing with Ext4 codebase.
     def append_ext4_event_options

data/lib/jsduck/app.rb

@@ -94,6 +94,7 @@ module JsDuck
       end
       agr.classify_orphans
       agr.create_global_class
+      agr.remove_ignored_classes
       agr.create_accessors
       agr.append_ext4_event_options
       agr.result

data/lib/jsduck/app_data.rb

@@ -24,7 +24,7 @@ module JsDuck
           :examples => @assets.examples.to_array,
           :search => SearchData.new.create(@relations.classes),
           :stats => @opts.stats ? Stats.new.create(@relations.classes) : [],
-          :signatures => signatures,
+          :signatures => MetaTagRegistry.instance.signatures,
           :localStorageDb => @opts.local_storage_db,
           :showPrintButton => @opts.seo,
           :touchExamplesUi => @opts.touch_examples_ui,
@@ -33,13 +33,6 @@ module JsDuck
       File.open(filename, 'w') {|f| f.write(js) }
     end
 
-    def signatures
-      sigs = MetaTagRegistry.instance.signatures
-      # Inject private to meta tag signatures list
-      sigs << {:key => 'private', :long => 'private', :short => 'PRI'}
-      sigs
-    end
-
   end
 
 end

data/lib/jsduck/app_exporter.rb

@@ -43,8 +43,6 @@ module JsDuck
       [:name, :tagname, :owner, :meta, :id].each do |key|
         m_copy[key] = m[key]
       end
-      # Inject :private to meta.
-      m_copy[:meta][:private] = true if m[:private]
       m_copy
     end
 

data/lib/jsduck/assets.rb

@@ -28,20 +28,18 @@ module JsDuck
 
       @images = Images.new(@opts.images)
       @welcome = Welcome.create(@opts.welcome)
-      @guides = Guides.create(@opts.guides, DocFormatter.new(@relations, @opts))
+      @guides = Guides.create(@opts.guides, DocFormatter.new(@relations, @opts), @opts)
       @videos = Videos.create(@opts.videos)
       @examples = Examples.create(@opts.examples, @opts)
       @categories = Categories.create(@opts.categories_path, DocFormatter.new(@relations, @opts), @relations)
     end
 
     # Writes out the assets that can be written out separately:
-    # guides, videos, examples, images.
+    # guides, images.
     #
     # Welcome page and categories are written in JsDuck::IndexHtml
     def write
       @guides.write(@opts.output_dir+"/guides")
-      @videos.write(@opts.output_dir+"/videos")
-      @examples.write(@opts.output_dir+"/examples")
       @images.copy(@opts.output_dir+"/images")
     end
 

data/lib/jsduck/class.rb

@@ -150,7 +150,7 @@ module JsDuck
       ms = parent ? parent.members_hash(type, context) : {}
 
       mixins.each do |mix|
-        ms.merge!(mix.members_hash(type, context)) {|k,o,n| store_overrides(k,o,n)}
+        merge!(ms, mix.members_hash(type, context))
       end
 
       # For static members, exclude everything not explicitly marked as inheritable
@@ -158,19 +158,38 @@ module JsDuck
         ms.delete_if {|key, member| !member[:inheritable] }
       end
 
-      ms.merge!(local_members_hash(type, context)) {|k,o,n| store_overrides(k,o,n)}
+      merge!(ms, local_members_hash(type, context))
 
       # If singleton has static members, include them as if they were
       # instance members.  Otherwise they will be completely excluded
       # from the docs, as the static members block is not created for
       # singletons.
       if @doc[:singleton] && @doc[:statics][type].length > 0
-        ms.merge!(local_members_hash(type, :statics)) {|k,o,n| store_overrides(k,o,n)}
+        merge!(ms, local_members_hash(type, :statics))
       end
 
       ms
     end
 
+    # merges second members hash into first one
+    def merge!(hash1, hash2)
+      hash2.each_pair do |name, m|
+        if m[:meta] && m[:meta][:hide]
+          if hash1[name]
+            hash1.delete(name)
+          else
+            ctx = m[:files][0]
+            Logger.instance.warn(:hide, "@hide used but #{m[:tagname]} #{m[:name]} not found in parent class", ctx[:filename], ctx[:linenr])
+          end
+        else
+          if hash1[name]
+            store_overrides(hash1[name], m)
+          end
+          hash1[name] = m
+        end
+      end
+    end
+
     # Invoked when merge! finds two members with the same name.
     # New member always overrides the old, but inside new we keep
     # a list of members it overrides.  Normally one member will
@@ -179,7 +198,7 @@ module JsDuck
     # ExtJS, we have to handle it.
     #
     # Every overridden member is listed just once.
-    def store_overrides(key, old, new)
+    def store_overrides(old, new)
       # Sometimes a class is included multiple times (like Ext.Base)
       # resulting in its members overriding themselves.  Because of
       # this, ignore overriding itself.
@@ -187,7 +206,6 @@ module JsDuck
         new[:overrides] = [] unless new[:overrides]
         new[:overrides] << old unless new[:overrides].any? {|m| m[:owner] == old[:owner] }
       end
-      new
     end
 
     # Helper method to get the direct members of this class
@@ -267,6 +285,17 @@ module JsDuck
       Class.short_name(@doc[:name])
     end
 
+    # Returns CSS icons class for the class
+    def icon
+      if @doc[:singleton]
+        "icon-singleton"
+      elsif inherits_from?("Ext.Component")
+        "icon-component"
+      else
+        "icon-class"
+      end
+    end
+
     # Static methods
 
     # Utility method that given a package or class name finds the name

data/lib/jsduck/class_formatter.rb

@@ -27,8 +27,8 @@ module JsDuck
       cls[:doc] = @formatter.format(cls[:doc]) if cls[:doc]
       [:members, :statics].each do |group|
         cls[group].each_pair do |type, members|
-          # format all members
-          cls[group][type] = members.map {|m| format_member(m) }
+          # format all members (except hidden ones)
+          cls[group][type] = members.map {|m| m[:meta][:hide] ? m : format_member(m)  }
         end
       end
       cls[:html_meta] = format_meta_data(cls)

data/lib/jsduck/doc_parser.rb

@@ -134,8 +134,6 @@ module JsDuck
           at_var
         elsif look(/@inheritable\b/)
           boolean_at_tag(/@inheritable/, :inheritable)
-        elsif look(/@(private|ignore|hide)\b/)
-          boolean_at_tag(/@(private|ignore|hide)/, :private)
         elsif look(/@accessor\b/)
           boolean_at_tag(/@accessor/, :accessor)
         elsif look(/@evented\b/)

data/lib/jsduck/examples.rb

@@ -48,14 +48,6 @@ module JsDuck
       end
     end
 
-    # Writes examples JSON file to dir
-    def write(dir)
-      FileUtils.mkdir(dir) unless File.exists?(dir)
-      # Write the JSON to output dir, so it's available in released
-      # version of docs and people can use it with JSDuck by themselves.
-      JsonDuck.write_json(dir+"/examples.json", @groups)
-    end
-
     # Extracts example icon URL from example hash
     def icon_url(example)
       @opts.examples_base_url + example["icon"]

data/lib/jsduck/grouped_asset.rb

@@ -10,13 +10,20 @@ module JsDuck
   class GroupedAsset
     # Should be called from constructor after @groups have been read in,
     # and after it's been ensured that all items in groupes have names.
+    #
+    # Prints warning when there is a duplicate item within a group.
+    # The warning message should say something like "duplicate <asset type>"
     def build_map_by_name(warning_msg)
       @map_by_name = {}
-      each_item do |item|
-        if @map_by_name[item["name"]]
-          Logger.instance.warn(nil, "#{warning_msg} '#{item['name']}'")
+      @groups.each do |group|
+        group_map = {}
+        group["items"].each do |item|
+          if group_map[item["name"]]
+            Logger.instance.warn(:dup_asset, "#{warning_msg} '#{item['name']}'")
+          end
+          @map_by_name[item["name"]] = item
+          group_map[item["name"]] = item
         end
-        @map_by_name[item["name"]] = item
       end
     end
 

data/lib/jsduck/guides.rb

@@ -10,43 +10,33 @@ module JsDuck
   # Reads in guides and converts them to JsonP files
   class Guides < GroupedAsset
     # Creates Guides object from filename and formatter
-    def self.create(filename, formatter)
+    def self.create(filename, formatter, opts)
       if filename
-        Guides.new(filename, formatter)
+        Guides.new(filename, formatter, opts)
       else
         NullObject.new(:to_array => [], :to_html => "", :[] => nil)
       end
     end
 
     # Parses guides config file
-    def initialize(filename, formatter)
+    def initialize(filename, formatter, opts)
       @path = File.dirname(filename)
       @groups = JsonDuck.read(filename)
       build_map_by_name("Two guides have the same name")
       @formatter = formatter
+      @opts = opts
     end
 
     # Writes all guides to given dir in JsonP format
     def write(dir)
       FileUtils.mkdir(dir) unless File.exists?(dir)
       each_item {|guide| write_guide(guide, dir) }
-      # Write the JSON to output dir, so it's available in released
-      # version of docs and people can use it with JSDuck by themselves.
-      JsonDuck.write_json(dir+"/guides.json", @groups)
     end
 
     def write_guide(guide, dir)
-      guide_dir = @path + "/guides/" + guide["name"]
-      tutorial_dir = @path + "/tutorials/" + guide["name"]
+      in_dir = @path + "/guides/" + guide["name"]
       out_dir = dir + "/" + guide["name"]
-
-      if File.exists?(guide_dir)
-        in_dir = guide_dir
-      elsif File.exists?(tutorial_dir)
-        in_dir = tutorial_dir
-      else
-        return Logger.instance.warn(:guide, "Guide #{guide_dir} / #{tutorial_dir} not found")
-      end
+      return Logger.instance.warn(:guide, "Guide #{in_dir} not found") unless File.exists?(in_dir)
 
       guide_file = in_dir + "/README.md"
       return Logger.instance.warn(:guide, "README.md not found in #{in_dir}") unless File.exists?(guide_file)
@@ -55,6 +45,9 @@ module JsDuck
       # Copy the whole guide dir over
       FileUtils.cp_r(in_dir, out_dir)
 
+      # Ensure the guide has an icon
+      fix_icon(out_dir)
+
       @formatter.doc_context = {:filename => guide_file, :linenr => 0}
       name = File.basename(in_dir)
       @formatter.img_path = "guides/#{name}"
@@ -63,6 +56,19 @@ module JsDuck
       JsonDuck.write_jsonp(out_dir+"/README.js", name, {:guide => html, :title => guide["title"]})
     end
 
+    # Ensures the guide dir contains icon.png.
+    # When there isn't looks for icon-lg.png and renames it to icon.png.
+    # When neither exists, copies over default icon.
+    def fix_icon(dir)
+      if File.exists?(dir+"/icon.png")
+        # All ok
+      elsif File.exists?(dir+"/icon-lg.png")
+        FileUtils.mv(dir+"/icon-lg.png", dir+"/icon.png")
+      else
+        FileUtils.cp(@opts.template_dir+"/resources/images/default-guide.png", dir+"/icon.png")
+      end
+    end
+
     # Creates table of contents at the top of guide by looking for <h2> elements in HTML.
     def add_toc(guide, html)
       toc = [

data/lib/jsduck/icons.rb

@@ -9,20 +9,10 @@ module JsDuck
           :name => cls[:name],
           :extends => cls[:extends],
           :private => cls[:private],
-          :icon => icon(cls),
+          :icon => cls.icon,
         }
       end
     end
-
-    def icon(cls)
-      if cls[:singleton]
-        "icon-singleton"
-      elsif cls.inherits_from?("Ext.Component")
-        "icon-component"
-      else
-        "icon-class"
-      end
-    end
   end
 
 end

data/lib/jsduck/logger.rb

@@ -25,6 +25,7 @@ module JsDuck
         [:no_doc, "Member or class without documentation"],
         [:dup_param, "Method has two parameters with the same name"],
         [:dup_member, "Class has two members with the same name"],
+        [:dup_asset, "Duplicate guide/video/example"],
         [:req_after_opt, "Required parameter comes after optional"],
         [:subproperty, "@param foo.bar where foo param doesn't exist"],
         [:sing_static, "Singleton class member marked as @static"],
@@ -37,7 +38,9 @@ module JsDuck
         [:cat_no_match, "Class pattern in categories file matches nothing"],
         [:cat_class_missing, "Class is missing from categories file"],
         [:guide, "Guide is missing from --guides dir"],
+
         [:aside, "Problem with @aside tag"],
+        [:hide, "Problem with @hide tag"],
       ]
       # Turn off all warnings by default.
       # This is good for testing.

data/lib/jsduck/merger.rb

@@ -227,12 +227,15 @@ module JsDuck
     # Detects properties common for each doc-object and adds them
     def add_shared(hash, doc_map)
       hash.merge!({
-        :private => !!doc_map[:private],
         :inheritable => !!doc_map[:inheritable],
         :inheritdoc => doc_map[:inheritdoc] ? doc_map[:inheritdoc].first : nil,
         :meta => detect_meta(doc_map),
       })
+      # copy :private also to main hash
+      hash[:private] = true if hash[:meta][:private]
+
       hash[:id] = create_member_id(hash)
+
       return hash
     end
 
@@ -279,7 +282,7 @@ module JsDuck
         elsif code[:type] == :assignment && code[:right]
           if code[:right][:type] == :function
             return "Function"
-          elsif code[:right][:type] == :literal
+          elsif code[:right][:type] == :literal && code[:right][:class] != nil
             return code[:right][:class]
           end
         end

data/lib/jsduck/meta_tag_registry.rb

@@ -1,11 +1,27 @@
-require 'singleton'
 require "jsduck/meta_tag_loader"
 
 module JsDuck
 
   # Access to meta-tags
   class MetaTagRegistry
-    include Singleton
+
+    @@instance = nil
+
+    # Returns singleton instance of MetaTagRegistry.
+    # By default this will be auto-loaded with builtin tags.
+    def self.instance
+      if !@@instance
+        @@instance = MetaTagRegistry.new
+        @@instance.load([:builtins])
+      end
+      @@instance
+    end
+
+    # Allows injecting another MetaTagRegistry to be used as a global instance.
+    def self.instance=(instance)
+      @@instance = instance
+    end
+
 
     def initialize
       @tags = []
@@ -34,7 +50,17 @@ module JsDuck
     # Returns array of all available tag instances.
     # When position provided, returns only tags in that position
     def tags(position=nil)
-      position ? @tags.find_all {|t| t.position == position} : @tags
+      return @tags unless position
+
+      unless @position_map
+        @position_map = {}
+        @tags.each do |t|
+          @position_map[t.position] = [] unless @position_map[t.position]
+          @position_map[t.position] << t
+        end
+      end
+
+      @position_map[position] || []
     end
 
     # Accesses tag by key or name

data/lib/jsduck/options.rb

@@ -72,7 +72,7 @@ module JsDuck
       ]
       @meta_tag_paths = []
 
-      @version = "3.5.0"
+      @version = "3.6.0"
 
       # Customizing output
       @title = "Sencha Docs - Ext JS"
@@ -124,7 +124,10 @@ module JsDuck
         read_filenames(canonical(fname))
       end
       validate
-      MetaTagRegistry.instance.load([:builtins] + @meta_tag_paths)
+
+      reg = MetaTagRegistry.new
+      reg.load([:builtins] + @meta_tag_paths)
+      MetaTagRegistry.instance = reg
     end
 
     def create_option_parser

data/lib/jsduck/renderer.rb

@@ -239,8 +239,6 @@ module JsDuck
       MetaTagRegistry.instance.signatures.each do |s|
         after += "<strong class='#{s[:key]} signature'>#{s[:long]}</strong>" if m[:meta][s[:key]]
       end
-      # Special case for :private which isn't inside :meta.
-      after += "<strong class='private signature'>private</strong>" if m[:private]
 
       uri = "#!/api/#{m[:owner]}-#{m[:id]}"
 

data/lib/jsduck/search_data.rb

@@ -41,10 +41,9 @@ module JsDuck
         :cls => alias_display_name(key)+": "+name,
         :member => name,
         :type => :class,
-        :icon => :subclass,
+        :icon => cls.icon,
         :id => cls.full_name,
-        :private => cls[:private],
-        :removed => cls[:meta][:removed],
+        :meta => cls[:meta],
         :sort => 0,
       }
     end
@@ -55,10 +54,9 @@ module JsDuck
         :cls => cls.full_name,
         :member => cls.short_name,
         :type => :class,
-        :icon => :class,
+        :icon => cls.icon,
         :id => cls.full_name,
-        :private => cls[:private],
-        :removed => cls[:meta][:removed],
+        :meta => cls[:meta],
         :sort => 1,
       }
     end
@@ -69,10 +67,9 @@ module JsDuck
         :cls => name,
         :member => Class.short_name(name),
         :type => :class,
-        :icon => :subclass,
+        :icon => cls.icon,
         :id => cls.full_name,
-        :private => cls[:private],
-        :removed => cls[:meta][:removed],
+        :meta => cls[:meta],
         :sort => 2,
       }
     end
@@ -83,10 +80,9 @@ module JsDuck
         :cls => cls.full_name,
         :member => member[:name],
         :type => :member,
-        :icon => member[:tagname],
+        :icon => "icon-" + member[:tagname].to_s,
         :id => cls.full_name + "-" + member[:id],
-        :private => member[:private],
-        :removed => member[:meta][:removed],
+        :meta => member[:meta],
         :sort => 3,
       }
     end

data/lib/jsduck/tag/hide.rb

@@ -0,0 +1,18 @@
+require "jsduck/meta_tag"
+
+module JsDuck::Tag
+  # Implementation of @hide tag.
+  #
+  # Hides a member in parent class.
+  #
+  # The core of the implementation is built into jsduck.
+  #
+  class Hide < JsDuck::MetaTag
+    def initialize
+      @name = "hide"
+      @key = :hide
+      @boolean = true
+    end
+  end
+end
+

data/lib/jsduck/tag/ignore.rb

@@ -0,0 +1,13 @@
+require "jsduck/meta_tag"
+
+module JsDuck::Tag
+  # @ignore is alias for @private
+  class Ignore < JsDuck::MetaTag
+    def initialize
+      @name = "ignore"
+      @key = :ignore
+      @boolean = true
+    end
+  end
+end
+

data/lib/jsduck/tag/private.rb

@@ -0,0 +1,20 @@
+require "jsduck/meta_tag"
+
+module JsDuck::Tag
+  # Implementation of @private tag.
+  #
+  # Marks class/member as private.
+  #
+  # Because :private is accessed a lot internally, it's also injected
+  # to the main hash of documentation item.
+  #
+  class Private < JsDuck::MetaTag
+    def initialize
+      @name = "private"
+      @key = :private
+      @boolean = true
+      @signature = {:long => "private", :short => "PRI"}
+    end
+  end
+end
+

data/lib/jsduck/videos.rb

@@ -30,14 +30,6 @@ module JsDuck
       end
     end
 
-    # Writes videos JSON file to a dir
-    def write(dir)
-      FileUtils.mkdir(dir) unless File.exists?(dir)
-      # Write the JSON to output dir, so it's available in released
-      # version of docs and people can use it with JSDuck by themselves.
-      JsonDuck.write_json(dir+"/videos.json", @groups)
-    end
-
     # Extracts video icon URL from video hash
     def icon_url(video)
       video["thumb"]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: jsduck
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 31
   prerelease: false
   segments: 
   - 3
-  - 5
+  - 6
   - 0
-  version: 3.5.0
+  version: 3.6.0
 platform: ruby
 authors: 
 - Rene Saarsoo
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-02-15 00:00:00 +02:00
+date: 2012-02-20 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -135,8 +135,11 @@ files:
 - lib/jsduck/tag/author.rb
 - lib/jsduck/tag/deprecated.rb
 - lib/jsduck/tag/docauthor.rb
+- lib/jsduck/tag/hide.rb
+- lib/jsduck/tag/ignore.rb
 - lib/jsduck/tag/markdown.rb
 - lib/jsduck/tag/preventable.rb
+- lib/jsduck/tag/private.rb
 - lib/jsduck/tag/protected.rb
 - lib/jsduck/tag/readonly.rb
 - lib/jsduck/tag/removed.rb
@@ -193,6 +196,7 @@ files:
 - template-min/resources/images/iphone-small-l.jpg
 - template-min/resources/images/ipad-p.jpg
 - template-min/resources/images/text-bg.gif
+- template-min/resources/images/default-guide.png
 - template-min/resources/images/loading-title.png
 - template-min/resources/images/version-tabs.png
 - template-min/resources/images/more.png