jsduck 3.4.1 → 3.5.0

data/Rakefile

@@ -154,14 +154,6 @@ class JsDuckRunner
     @options += options
   end
 
-  def add_relative_examples_path
-    @options += ["--head-html", <<-EOHTML]
-      <script type="text/javascript">
-        Docs.exampleBaseUrl = "#{relative_sdk_path}examples/";
-      </script>
-    EOHTML
-  end
-
   # Enables comments when CORS is supported by browser.
   # This excludes Opera and IE < 8.
   # We check explicitly for IE version to make sure the code works the
@@ -222,7 +214,7 @@ class JsDuckRunner
 
   def set_touch2_src
     relative_touch_path = "../"
-    system("cp", "-r", "#{@sdk_dir}/touch/docs/welcome.html", "template-min/welcome.html")
+    system("cp", "-r", "#{@sdk_dir}/touch/docs/build-welcome.html", "template-min/welcome.html")
     system("cp", "-r", "#{@sdk_dir}/touch/docs/eg-iframe.html", "template-min/eg-iframe.html")
 
     ["template-min/eg-iframe.html", "template-min/welcome.html"].each do |file|
@@ -240,7 +232,6 @@ class JsDuckRunner
 
     head_html = <<-EOHTML
       <script type="text/javascript">
-        Docs.exampleBaseUrl = "#{relative_touch_path}examples/";
         if (Ext.is.Phone) { window.location = "#{relative_touch_path}examples/"; }
       </script>
     EOHTML
@@ -248,7 +239,8 @@ class JsDuckRunner
     @options += [
       "--body-html", head_html,
       "--welcome", "template-min/welcome.html",
-      "--eg-iframe", "template-min/eg-iframe.html"
+      "--eg-iframe", "template-min/eg-iframe.html",
+      "--examples-base-url", "#{relative_touch_path}examples/",
     ]
   end
 
@@ -475,7 +467,11 @@ task :touch2, [:mode] => :sass do |t, args|
   runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/touch/docs/config.json"]
   runner.add_debug if mode == "debug"
   runner.add_export_notice("touch/2-0") if mode == "export"
-  runner.set_touch2_src if mode == "export"
+  if mode == "export"
+    runner.set_touch2_src
+  else
+    runner.add_options ["--examples-base-url", "touch/examples/"]
+  end
   runner.add_seo if mode == "debug" || mode == "live"
   runner.add_google_analytics if mode == "live"
   runner.add_comments('comments-touch-2') if mode == "debug" || mode == "live"

data/bin/compare

@@ -36,12 +36,16 @@ def read_ignored_members(filename)
   map
 end
 
+def normal_public_member?(m)
+  !m["private"] && !m["meta"]["protected"] && !m["meta"]["deprecated"] && !m["meta"]["removed"]
+end
+
 # Gathers class members that are in cls1, but are missing in cls2
 # Ignoring members listed in ignored_members hash.
 def compare_classes(cls1, cls2, ignored_members)
   diff = []
   cls1["members"].each_pair do |group_name, group_items|
-    group_items.find_all {|m1| !m1["private"] && !m1["meta"]["protected"] && m1["owner"] == cls1["name"] }.each do |m1|
+    group_items.find_all {|m1| normal_public_member?(m1) && m1["owner"] == cls1["name"] }.each do |m1|
       match = cls2["members"][group_name].find do |m2|
         m2["name"] == m1["name"] && !m2["meta"]["protected"] && !m2["private"]
       end
@@ -68,22 +72,34 @@ def compare_classes(cls1, cls2, ignored_members)
 end
 
 
-
 old_classes = read_all_classes(ARGV[0], :ignore_private)
 new_classes = read_all_classes(ARGV[1])
 out_file = ARGV[2]
 ignored_members = ARGV[3] ? read_ignored_members(ARGV[3]) : {}
 
+# Explicit remapping of classes
+remap = {
+  "Array" => "Ext.Array",
+  "Date" => "Ext.Date",
+  "Function" => "Ext.Function",
+  "Number" => "Ext.Number",
+  "String" => "Ext.String",
+  "Ext.supports" => "Ext.feature.has",
+}
+
 diff_data = []
 old_classes.each_pair do |name, cls|
+  # only go through classes, not alternate names
   if name == cls["name"]
-    new_cls = new_classes[cls["name"]]
-    # Remap classes like Array to Ext.Array
-    new_cls = new_classes["Ext."+cls["name"]] unless new_cls
+    if remap[name]
+      new_cls = new_classes[remap[name]]
+    else
+      new_cls = new_classes[name]
+    end
 
     diff_data << {
       :name => cls["name"],
-      :found => !!new_cls,
+      :found => !!new_cls || ignored_members[name],
       :new_name => new_cls && new_cls["name"],
       :diff => new_cls ? compare_classes(cls, new_cls, ignored_members) : [],
     }

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.4.1'
-  s.date = '2012-01-30'
+  s.version = '3.5.0'
+  s.date = '2012-02-15'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"

data/lib/jsduck/accessors.rb

@@ -83,12 +83,7 @@ module JsDuck
       return add_shared({
         :tagname => :event,
         :name => name,
-        :doc =>
-          "Fires when the {@link ##{cfg[:id]}} configuration is changed by {@link #method-#{setter_name}}." +
-          "\n\n" +
-          "Note that this event is fired *before* the value of {@link ##{cfg[:id]}} has been updated, " +
-          "and that you can return false from any listener to the #{name} event " +
-          "to cancel the change.",
+        :doc => "Fires when the {@link ##{cfg[:id]}} configuration is changed by {@link #method-#{setter_name}}.",
         :params => [
           {
             :name => "this",

data/lib/jsduck/app.rb

@@ -8,12 +8,7 @@ require 'jsduck/relations'
 require 'jsduck/inherit_doc'
 require 'jsduck/parallel_wrap'
 require 'jsduck/logger'
-require 'jsduck/welcome'
-require 'jsduck/guides'
-require 'jsduck/videos'
-require 'jsduck/examples'
-require 'jsduck/categories'
-require 'jsduck/images'
+require 'jsduck/assets'
 require 'jsduck/json_duck'
 require 'jsduck/lint'
 require 'jsduck/template_dir'
@@ -48,12 +43,11 @@ module JsDuck
       InheritDoc.new(@relations).resolve_all
       Lint.new(@relations).run
 
-      @images = Images.new(@opts.images)
-      @welcome = Welcome.create(@opts.welcome)
-      @guides = Guides.create(@opts.guides, DocFormatter.new(@relations, @opts))
-      @videos = Videos.create(@opts.videos)
-      @examples = Examples.create(@opts.examples)
-      @categories = Categories.create(@opts.categories_path, DocFormatter.new(@relations, @opts), @relations)
+      # Initialize guides, videos, examples, ...
+      @assets = Assets.new(@relations, @opts)
+
+      # Give access to assets from all meta-tags
+      MetaTagRegistry.instance.assets = @assets
 
       if @opts.export
         format_classes
@@ -65,17 +59,9 @@ module JsDuck
         FileUtils.rm_rf(@opts.output_dir)
         TemplateDir.new(@opts).write
 
-        index = IndexHtml.new(@opts)
-        index.welcome = @welcome
-        index.categories = @categories
-        index.guides = @guides
-        index.write
+        IndexHtml.new(@assets, @opts).write
 
-        app_data = AppData.new(@relations, @opts)
-        app_data.guides = @guides
-        app_data.videos = @videos
-        app_data.examples = @examples
-        app_data.write(@opts.output_dir+"/data.js")
+        AppData.new(@relations, @assets, @opts).write(@opts.output_dir+"/data.js")
 
         # class-formatting is done in parallel which breaks the links
         # between source files and classes. Therefore it MUST to be done
@@ -87,10 +73,7 @@ module JsDuck
         cw = ClassWriter.new(AppExporter, @relations, @opts)
         cw.write(@opts.output_dir+"/output", ".js")
 
-        @guides.write(@opts.output_dir+"/guides")
-        @videos.write(@opts.output_dir+"/videos")
-        @examples.write(@opts.output_dir+"/examples")
-        @images.copy(@opts.output_dir+"/images")
+        @assets.write
       end
     end
 
@@ -160,7 +143,7 @@ module JsDuck
       # Then merge the data back to classes sequentially
       formatted_classes.each do |cls|
         @relations[cls[:doc][:name]].internal_doc = cls[:doc]
-        cls[:images].each {|img| @images.add(img) }
+        cls[:images].each {|img| @assets.images.add(img) }
       end
     end
 

data/lib/jsduck/app_data.rb

@@ -8,12 +8,9 @@ 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)
+    def initialize(relations, assets, opts)
       @relations = relations
+      @assets = assets
       @opts = opts
     end
 
@@ -22,9 +19,9 @@ module JsDuck
       js = "Docs = " + JsonDuck.generate({
         :data => {
           :classes => Icons.new.create(@relations.classes),
-          :guides => @guides.to_array,
-          :videos => @videos.to_array,
-          :examples => @examples.to_array,
+          :guides => @assets.guides.to_array,
+          :videos => @assets.videos.to_array,
+          :examples => @assets.examples.to_array,
           :search => SearchData.new.create(@relations.classes),
           :stats => @opts.stats ? Stats.new.create(@relations.classes) : [],
           :signatures => signatures,

data/lib/jsduck/assets.rb

@@ -0,0 +1,50 @@
+require 'jsduck/images'
+require 'jsduck/welcome'
+require 'jsduck/guides'
+require 'jsduck/videos'
+require 'jsduck/examples'
+require 'jsduck/categories'
+require 'jsduck/doc_formatter'
+
+module JsDuck
+
+  # Binds together: Welcome page, Categories, Images, Guides, Videos,
+  # Examples.
+  #
+  # Often we need to pass guides/videos/examples/... to several
+  # classes. Having all these assets together in here, means we just
+  # need to pass one value instead of 3 or more.
+  class Assets
+    attr_reader :images
+    attr_reader :welcome
+    attr_reader :guides
+    attr_reader :videos
+    attr_reader :examples
+    attr_reader :categories
+
+    def initialize(relations, opts)
+      @relations = relations
+      @opts = opts
+
+      @images = Images.new(@opts.images)
+      @welcome = Welcome.create(@opts.welcome)
+      @guides = Guides.create(@opts.guides, DocFormatter.new(@relations, @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.
+    #
+    # 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
+
+  end
+
+end

data/lib/jsduck/class.rb

@@ -8,8 +8,16 @@ module JsDuck
   class Class
     attr_accessor :relations
 
-    def initialize(doc)
+    # Creates JSDuck class.
+    #
+    # Pass true as second parameter to create a placeholder class.
+    def initialize(doc, class_exists=true)
       @doc = doc
+
+      # Wrap classname into custom string class that allows
+      # differenciating between existing and missing classes.
+      @doc[:name] = ClassNameString.new(@doc[:name], class_exists)
+
       @doc[:members] = Class.default_members_hash if !@doc[:members]
       @doc[:statics] = Class.default_members_hash if !@doc[:statics]
       @relations = nil
@@ -44,15 +52,25 @@ module JsDuck
       p ? p.superclasses + [p]  : []
     end
 
-    # Returns array of mixin class instances.
-    # Returns empty array if no mixins
+    # Returns all direct mixins of this class. Same as #deps(:mixins).
     def mixins
-      @doc[:mixins] ? @doc[:mixins].collect {|classname| lookup(classname) }.compact : []
+      deps(:mixins)
+    end
+
+    # Returns an array of class instances this class directly depends on.
+    # Possible types are:
+    #
+    # - :mixins
+    # - :requires
+    # - :uses
+    #
+    def deps(type)
+      @doc[type] ? @doc[type].collect {|classname| lookup(classname) } : []
     end
 
-    # Returns all mixins this class and its parent classes
-    def all_mixins
-      mixins + (parent ? parent.all_mixins : [])
+    # Same ase #deps, but pulls out the dependencies from all parent classes.
+    def parent_deps(type)
+      parent ? parent.deps(type) + parent.parent_deps(type) : []
     end
 
     # Looks up class object by name
@@ -60,10 +78,18 @@ module JsDuck
     def lookup(classname)
       if @relations[classname]
         @relations[classname]
-      elsif !@relations.ignore?(classname)
+      elsif @relations.ignore?(classname) || classname =~ /\*/
+        # Ignore explicitly ignored classes and classnames with
+        # wildcards in them.  We could expand the wildcard, but that
+        # can result in a very long list of classes, like when
+        # somebody requires 'Ext.form.*', so for now we do the
+        # simplest thing and ignore it.
+        Class.new({:name => classname}, false)
+      else
         context = @doc[:files][0]
         Logger.instance.warn(:extend, "Class #{classname} not found", context[:filename], context[:linenr])
-        nil
+        # Create placeholder class
+        Class.new({:name => classname}, false)
       end
     end
 
@@ -276,4 +302,21 @@ module JsDuck
     end
   end
 
+  # String class for classnames that has extra method #exists? which
+  # returns false when class with such name doesn't exist.
+  #
+  # This ability is used by JsDuck::Renderer, which only receives
+  # names of various classes but needs to only render existing classes
+  # as links.
+  class ClassNameString < String
+    def initialize(str, exists=true)
+      super(str)
+      @exists = exists
+    end
+
+    def exists?
+      @exists
+    end
+  end
+
 end

data/lib/jsduck/examples.rb

@@ -1,22 +1,51 @@
 require 'jsduck/json_duck'
 require 'jsduck/null_object'
+require 'jsduck/grouped_asset'
 
 module JsDuck
 
   # Reads in examples JSON file
-  class Examples
+  class Examples < GroupedAsset
     # Creates Examples object from filename.
-    def self.create(filename)
+    def self.create(filename, opts)
       if filename
-        Examples.new(filename)
+        Examples.new(filename, opts)
       else
-        NullObject.new(:to_array => [])
+        NullObject.new(:to_array => [], :[] => nil)
       end
     end
 
     # Parses examples config file
-    def initialize(filename)
-      @examples = JsonDuck.read(filename)
+    def initialize(filename, opts)
+      @groups = JsonDuck.read(filename)
+      @opts = opts
+      fix_examples_data
+      build_map_by_name("Two examples have the same name")
+    end
+
+    # Prefix all relative URL-s in examples list with path given in --examples-base-url
+    #
+    # For backwards compatibility:
+    #
+    # - Create names for each example when not present
+    # - Create title from text
+    # - Create description from desc
+    #
+    def fix_examples_data
+      each_item do |ex|
+        unless ex["url"] =~ /^https?:\/\//
+          ex["url"] = @opts.examples_base_url + ex["url"]
+          ex["name"] = ex["url"] unless ex["name"]
+          unless ex["title"]
+            ex["title"] = ex["text"]
+            ex.delete("text")
+          end
+          unless ex["description"]
+            ex["description"] = ex["desc"]
+            ex.delete("desc")
+          end
+        end
+      end
     end
 
     # Writes examples JSON file to dir
@@ -24,12 +53,12 @@ module JsDuck
       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", @examples)
+      JsonDuck.write_json(dir+"/examples.json", @groups)
     end
 
-    # Returns all examples as array
-    def to_array
-      @examples
+    # Extracts example icon URL from example hash
+    def icon_url(example)
+      @opts.examples_base_url + example["icon"]
     end
 
   end