jsduck 3.1.0 → 3.2.1

data/README.md

@@ -77,15 +77,18 @@ documentation.  Guides, videos and examples will not be present.
 These can be added using more command line options as explained in the
 [Advanced Usage][adv] section of wiki.
 
-Running JSDuck against older Ext JS than 4.0.7 is expected to generate
-a lot of warnings.  Similarly your own .js files will probably
-generate warnings too.  Sorry for that, JSDuck just wants to be
-helpful.  If you are overwhelmed by the warnings, you can disable them
-using `--no-warnings` switch.  Another thing that often happens is
-that JSDuck is unable to determine into which class a member belongs
-and will place all such items into a global class - you can disable
-this using the `--ignore-global` switch.  For full list of command
-line options type `jsduck --help=full`.
+Running latest JSDuck is expected to generate lots of warnings.
+That's because some warning types were added after Ext JS 4.0.7
+release.  Sorry for that, JSDuck just wants to be helpful.  If you are
+overwhelmed by the warnings, you can disable them selectively using
+something like `--warnings=-link_ambiguous,-no_doc` or you could
+disable them all by `--warnings=-all`.
+
+Another thing that often happens is that JSDuck is unable to determine
+into which class a member belongs and will place all such items into a
+global class - you can disable this using the `--ignore-global`
+switch.  For full list of all command line options type
+`jsduck --help=full`.
 
 [adv]: https://github.com/senchalabs/jsduck/wiki/Advanced-Usage
 
@@ -100,7 +103,9 @@ Documenting your code
 ---------------------
 
 All the supported syntax is described in the [Guide][].
+For quick overview take a look at [example.js][example].
 
+[example]: https://github.com/senchalabs/jsduck/blob/master/opt/example.js
 
 Copying
 -------

data/Rakefile

@@ -154,34 +154,6 @@ class JsDuckRunner
     @options += options
   end
 
-  def add_sdk
-    head_html = <<-EOHTML
-      <link rel="canonical" href="http://docs.sencha.com/ext-js/4-0/" />
-      <meta name="description" content="Ext JS 4.0 API Documentation from Sencha. Class documentation, Guides and Videos on how to create Javascript applications with Ext JS 4" />
-    EOHTML
-
-    @options += [
-      "--title", "Sencha Docs - Ext JS 4.0",
-      "--head-html", head_html,
-      "--footer", "Ext JS 4.0.7 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> rev #{revision}",
-      "--welcome", "opt/extjs-welcome.html",
-      "--guides", "#{@sdk_dir}/extjs/docs/guides.json",
-      "--videos", "#{@sdk_dir}/extjs/docs/videos.json",
-      "--examples", "#{@sdk_dir}/extjs/examples/examples.json",
-      "--categories", "#{@sdk_dir}/extjs/docs/categories.json",
-      "--local-storage-db", "ext-4",
-      "--output", "#{@out_dir}",
-      "--builtin-classes",
-      "--images", "#{@sdk_dir}/extjs/docs/resources",
-      "--images", "#{@sdk_dir}/platform/docs/resources",
-      "--stats",
-      "#{@sdk_dir}/extjs/src",
-      "#{@sdk_dir}/platform/src",
-      "#{@sdk_dir}/platform/core/src",
-      "#{@sdk_dir}/extjs/examples/ux",
-    ]
-  end
-
   def add_relative_examples_path
     @options += ["--head-html", <<-EOHTML]
       <script type="text/javascript">
@@ -215,34 +187,10 @@ class JsDuckRunner
     end
   end
 
-  def add_ext3
-    head_html = <<-EOHTML
-      <link rel="canonical" href="http://docs.sencha.com/ext-js/3-4/" />
-      <meta name="description" content="Ext JS 3.4 API Documentation from Sencha. Class documentation, Guides and Videos on how to create Javascript applications with Ext JS 3.4" />
-    EOHTML
-
-    @options += [
-      "--title", "Sencha Docs - Ext JS 3.4",
-      "--footer", "Ext JS 3.4 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
-      "--categories", "#{@sdk_dir}/../ext-3.4.0/src/categories.json",
-      "--ignore-global",
-      "--local-storage-db", "ext-3",
-      "--output", "#{@out_dir}",
-      "#{@sdk_dir}/../ext-3.4.0/src/core",
-      "#{@sdk_dir}/../ext-3.4.0/src/data",
-      "#{@sdk_dir}/../ext-3.4.0/src/dd",
-      "#{@sdk_dir}/../ext-3.4.0/src/direct",
-      "#{@sdk_dir}/../ext-3.4.0/src/ext-core/src",
-      "#{@sdk_dir}/../ext-3.4.0/src/state",
-      "#{@sdk_dir}/../ext-3.4.0/src/util",
-      "#{@sdk_dir}/../ext-3.4.0/src/widgets"
-    ]
-  end
-
   def add_ext4
     @options += [
       "--title", "Sencha Docs - Ext JS 4.0",
-      "--footer", "Ext JS 4.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
+      "--footer", "Ext JS 4.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> VERSION. <a href='http://www.sencha.com/legal/terms-of-use/'>Terms of Use</a>",
       "--ignore-global",
       "--no-warnings",
       "--images", "#{@ext_dir}/docs/doc-resources",
@@ -252,74 +200,22 @@ class JsDuckRunner
     ]
   end
 
-  def add_touch
-    head_html = <<-EOHTML
-      <link rel="canonical" href="http://docs.sencha.com/touch/1-1/" />
-      <meta name="description" content="Sencha Touch 1.1 API Documentation from Sencha. Documentation on how to create Javascript applications with Sencha Touch" />
-    EOHTML
-
-    @options += [
-      "--title", "Sencha Docs - Touch 1.1",
-      "--head-html", head_html,
-      "--footer", "Sencha Touch 1.1 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
-      "--categories", "#{@sdk_dir}/touch/doc-resources/categories.json",
-      "--videos", "#{@sdk_dir}/touch/doc-resources/videos.json",
-      "--local-storage-db", "touch-1",
-      "--output", "#{@out_dir}",
-      "--external=google.maps.Map,google.maps.LatLng",
-      "--images", "#{@sdk_dir}/touch/doc-resources",
-      "#{@sdk_dir}/touch/resources/themes/stylesheets/sencha-touch/default",
-    ]
-
-    @options += extract_jsb_build_files("#{@sdk_dir}/touch/sencha-touch.jsb3")
-  end
-
-  def add_touch2
-    head_html = <<-EOHTML
-      <link rel="canonical" href="http://docs.sencha.com/touch/2-0/" />
-      <meta name="description" content="Sencha Touch 2.0 API Documentation from Sencha. Documentation on how to create Javascript applications with Sencha Touch" />
-    EOHTML
-
-    @options += [
-      "--title", "Sencha Docs - Touch 2.0",
-      "--head-html", head_html,
-      "--footer", "Sencha Touch 2.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
-      "--categories", "#{@sdk_dir}/touch/docs/categories.json",
-      "--welcome", "opt/touch-welcome.html",
-      "--videos", "#{@sdk_dir}/touch/docs/videos.json",
-      "--guides", "#{@sdk_dir}/touch/docs/guides.json",
-      "--examples", "#{@sdk_dir}/touch/docs/examples.json",
-      "--touch-examples-ui",
-      "--local-storage-db", "touch-2",
-      "--output", "#{@out_dir}",
-      "--external=google.maps.Map,google.maps.LatLng",
-      "--builtin-classes",
-      "--img", "<p class='screenshot'><img src='%u' alt='%a'><span>%a</span></p>",
-      "--eg-iframe", "opt/touch-iframe.html",
-      "--warnings=-image",
-      # "--stats",
-      "#{@sdk_dir}/touch/resources/themes/stylesheets/sencha-touch/default",
-    ]
-
-    @options += extract_jsb_build_files("#{@sdk_dir}/touch/touch.jsb3")
-  end
-
   def add_touch_export
     @options += [
       "--json",
       "--output", "#{@out_dir}/../export/touch1",
       "--external=google.maps.Map,google.maps.LatLng",
+      "#{@sdk_dir}/touch/sencha-touch.jsb3",
     ]
-    @options += extract_jsb_build_files("#{@sdk_dir}/touch/sencha-touch.jsb3")
   end
 
   def add_touch2_export
     @options += [
-      "--json",
+      "--export", "full",
       "--output", "#{@out_dir}/../export/touch2",
       "--external=google.maps.Map,google.maps.LatLng",
+      "#{@sdk_dir}/touch/touch.jsb3",
     ]
-    @options += extract_jsb_build_files("#{@sdk_dir}/touch/touch.jsb3")
   end
 
   def set_touch2_src
@@ -354,82 +250,6 @@ class JsDuckRunner
     ]
   end
 
-  def add_touch_charts
-    head_html = <<-EOHTML
-      <link rel="canonical" href="http://docs.sencha.com/touch-charts/1-0/" />
-      <meta name="description" content="Sencha Touch Charts 1.0 API Documentation. Documentation on how to create Charts with Sencha Touch" />
-    EOHTML
-
-    @options += [
-      "--title", "Sencha Docs - Touch Charts 1.0",
-      "--head-html", head_html,
-      "--footer", "Sencha Touch Charts 1.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a>",
-      "--categories", "#{@sdk_dir}/charts/docs/categories.json",
-      "--guides", "#{@sdk_dir}/charts/docs/guides.json",
-      "--images", "#{@sdk_dir}/charts/docs/resources",
-      "--local-storage-db", "touch-charts",
-      "--output", "#{@out_dir}"
-    ]
-
-    @options += extract_jsb_build_files("#{@sdk_dir}/charts/touch-charts.jsb3")
-  end
-
-  def add_sencha_io
-    head_html = <<-EOHTML
-      <link rel="canonical" href="http://docs.sencha.com/sencha-io/1-0/" />
-      <meta name="description" content="Sencha.io 1.0 API Documentation. Documentation on how to use the Sencha.io SDK" />
-    EOHTML
-
-    @options += [
-      "--title", "Sencha Docs - IO 1.0",
-      "--head-html", head_html,
-      "--footer", "Sencha.io 1.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a>",
-      "--guides", "#{@sdk_dir}/../sync/docs/guides.json",
-      "--images", "#{@sdk_dir}/../sync/docs/resources",
-      "--local-storage-db", "sencha-io",
-      "--ignore-global",
-      "--output", "#{@out_dir}"
-    ]
-
-    @options += extract_jsb_build_files("#{@sdk_dir}/../sync/sencha-io.jsb3")
-  end
-
-  def add_animator
-    head_html = <<-EOHTML
-      <link rel="canonical" href="http://docs.sencha.com/animator/1-0/" />
-      <meta name="description" content="Sencha Animator 1.0 API Documentation from Sencha. Documentation on how to create Javascript applications with Sencha Touch" />
-    EOHTML
-
-    @options += [
-      "--title", "Sencha Docs - Animator 1.0",
-      "--head-html", head_html,
-      "--footer", "Sencha Animator 1.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
-      # "--videos", "#{@animator_dir}/docs/videos.json",
-      "--guides", "#{@animator_dir}/docs/guides.json",
-      # "--examples", "#{@animator_dir}/docs/examples/examples.json",
-      "--local-storage-db", "animator",
-      "--output", "#{@out_dir}",
-    ]
-  end
-
-  # Extracts files of first build in jsb file
-  def extract_jsb_build_files(jsb_file)
-    json = JSON.parse(IO.read(jsb_file))
-    basedir = File.dirname(jsb_file)
-
-    return json["builds"][0]["packages"].map do |package_id|
-      package = json["packages"].find {|p| p["id"] == package_id }
-      package["files"].map do |file|
-        basedir + "/" + file["path"] + file["name"]
-      end
-    end.flatten
-  end
-
-  # Returns shortened hash of naming current git revision
-  def revision
-    `git rev-parse HEAD`.slice(0, 7)
-  end
-
   def add_debug
     @options += [
       "--extjs-path", "extjs/ext-all-debug.js",
@@ -444,21 +264,11 @@ class JsDuckRunner
     ]
   end
 
-  def add_sdk_export_notice
-    @options += [
-      "--body-html", <<-EOHTML
-      <div id="notice-text" style="display: none">
-        Use <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a> for up to date documentation and features
-      </div>
-      EOHTML
-    ]
-  end
-
-  def add_touch2_export_notice
+  def add_export_notice path
     @options += [
       "--body-html", <<-EOHTML
       <div id="notice-text" style="display: none">
-        Use <a href="http://docs.sencha.com/touch/2-0">http://docs.sencha.com/touch/2-0</a> for up to date documentation and features
+        Use <a href="http://docs.sencha.com/#{path}">http://docs.sencha.com/#{path}</a> for up to date documentation and features
       </div>
       EOHTML
     ]
@@ -530,6 +340,10 @@ class JsDuckRunner
           {
               text: 'Sencha Animator',
               href: 'http://docs.sencha.com/animator/1-0'
+          },
+          {
+              text: 'Sencha.io',
+              href: 'http://docs.sencha.com/io/1-0'
           }
         ];
       </script>
@@ -547,11 +361,6 @@ class JsDuckRunner
     system "cp -r #{@ext_dir}/welcome #{@out_dir}/extjs"
   end
 
-  def copy_animator_examples
-    system "mkdir -p #{@out_dir}/extjs"
-    system "cp -r #{@animator_dir}/docs/examples #{@out_dir}/extjs"
-  end
-
   # Copy over Sencha Touch
   def copy_touch2_build
     system "cp -r #{@sdk_dir}/touch/build #{@out_dir}/touch"
@@ -568,12 +377,6 @@ task :sass do
   system "compass compile --quiet template/resources/sass"
 end
 
-desc "Updates JSB3 file for Docs app.\n"+
-     "Run this before every commit that changes JS dependencies."
-task :jsb do
-  system("sencha", "create", "jsb", "-a", "template/build-js.html", "-p", "template/app.jsb3")
-end
-
 desc "Run JSDuck on Ext JS SDK (for internal use at Sencha)\n" +
      "sdk         - creates debug/development version\n" +
      "sdk[export] - creates export version\n" +
@@ -584,10 +387,10 @@ task :sdk, [:mode] => :sass do |t, args|
   compress if mode == "export" || mode == "live"
 
   runner = JsDuckRunner.new
-  runner.add_sdk
+  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/extjs/docs/config.json"]
   runner.add_debug if mode == "debug"
   runner.add_seo if mode == "debug" || mode == "live"
-  runner.add_sdk_export_notice if mode == "export"
+  runner.add_export_notice("ext-js/4-0") if mode == "export"
   runner.add_google_analytics if mode == "live"
   runner.add_comments('comments-ext-js-4') if mode == "debug" || mode == "live"
   runner.run
@@ -634,7 +437,7 @@ task :ext3, [:mode] => :sass do |t, args|
   compress if mode == "export"
 
   runner = JsDuckRunner.new
-  runner.add_ext3
+  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/../ext-3.4.0/src/doc-config.json"]
   runner.add_debug if mode == "debug"
   runner.add_seo if mode == "live"
   runner.add_google_analytics if mode == "live"
@@ -650,7 +453,7 @@ task :touch, [:mode] => :sass do |t, args|
   compress if mode == "live"
 
   runner = JsDuckRunner.new
-  runner.add_touch
+  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/touch/doc-resources/config.json"]
   runner.add_debug if mode == "debug"
   runner.add_seo if mode == "debug" || mode == "live"
   runner.add_google_analytics if mode == "live"
@@ -667,9 +470,9 @@ task :touch2, [:mode] => :sass do |t, args|
   compress if mode == "live" || mode == "export"
 
   runner = JsDuckRunner.new
-  runner.add_touch2
+  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/touch/docs/config.json"]
   runner.add_debug if mode == "debug"
-  runner.add_touch2_export_notice if mode == "export"
+  runner.add_export_notice("touch/2-0") if mode == "export"
   runner.set_touch2_src if mode == "export"
   runner.add_seo if mode == "debug" || mode == "live"
   runner.add_google_analytics if mode == "live"
@@ -689,7 +492,7 @@ task :charts, [:mode] => :sass do |t, args|
   compress if mode == "live"
 
   runner = JsDuckRunner.new
-  runner.add_touch_charts
+  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/charts/docs/config.json"]
   runner.add_debug if mode == "debug"
   runner.add_seo if mode == "debug" || mode == "live"
   runner.add_google_analytics if mode == "live"
@@ -706,26 +509,13 @@ task :senchaio, [:mode] => :sass do |t, args|
   compress if mode == "live"
 
   runner = JsDuckRunner.new
-  runner.add_sencha_io
+  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/../sync/docs/config.json"]
   runner.add_debug if mode == "debug"
   runner.add_seo if mode == "debug" || mode == "live"
   runner.add_google_analytics if mode == "live"
   runner.run
 end
 
-desc "Run JSDuck JSON Export (for internal use at Sencha)\n" +
-     "export[touch]  - creates export for Touch 1\n" +
-     "export[touch2] - creates export for Touch 2"
-task :export, [:mode] do |t, args|
-  mode = args[:mode]
-  throw "Unknown mode #{mode}" unless ["touch", "touch2"].include?(mode)
-
-  runner = JsDuckRunner.new
-  runner.add_touch_export if mode == "touch"
-  runner.add_touch2_export if mode == "touch2"
-  runner.run
-end
-
 desc "Run JSDuck on Sencha Animator (for internal use at Sencha)\n" +
      "animator         - creates debug/development version\n" +
      "animator[export] - create live version for deployment\n"
@@ -736,13 +526,24 @@ task :animator, [:mode] => :sass do |t, args|
   compress if mode == "live"
 
   runner = JsDuckRunner.new
-  runner.add_animator
+  runner.add_options ["--output", OUT_DIR, "--config", "#{ANIMATOR_DIR}/docs/config.json"]
   runner.add_debug if mode == "debug"
   runner.add_seo if mode == "debug" || mode == "live"
   runner.add_google_analytics if mode == "live"
   runner.run
+end
 
-  runner.copy_animator_examples
+desc "Run JSDuck JSON Export (for internal use at Sencha)\n" +
+     "export[touch]  - creates export for Touch 1\n" +
+     "export[touch2] - creates export for Touch 2"
+task :export, [:mode] do |t, args|
+  mode = args[:mode]
+  throw "Unknown mode #{mode}" unless ["touch", "touch2"].include?(mode)
+
+  runner = JsDuckRunner.new
+  runner.add_touch_export if mode == "touch"
+  runner.add_touch2_export if mode == "touch2"
+  runner.run
 end
 
 desc "Build JSDuck gem"

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.1.0'
-  s.date = '2011-11-16'
+  s.version = '3.2.1'
+  s.date = '2011-12-07'
   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

@@ -57,8 +57,7 @@ module JsDuck
         :owner => cfg[:owner],
         :files => cfg[:files],
         :id => "method-" + name,
-        :deprecated => cfg[:deprecated],
-        :meta => cfg[:meta],
+        :meta => clone_meta(cfg),
       }
     end
 
@@ -80,8 +79,7 @@ module JsDuck
         :owner => cfg[:owner],
         :files => cfg[:files],
         :id => "method-" + name,
-        :deprecated => cfg[:deprecated],
-        :meta => cfg[:meta]
+        :meta => clone_meta(cfg),
       }
     end
 
@@ -117,14 +115,24 @@ module JsDuck
         :owner => cfg[:owner],
         :files => cfg[:files],
         :id => "event-" + name,
-        :deprecated => cfg[:deprecated],
-        :meta => cfg[:meta]
+        :meta => clone_meta(cfg),
       }
     end
 
     def upcase_first(str)
       str[0,1].upcase + str[1..-1]
     end
+
+    # Create copy of all meta attributes of config, except the
+    # :required which only applies to configs and must not be
+    # propagated to methods or events.
+    def clone_meta(cfg)
+      h = {}
+      cfg[:meta].each_pair do |key, value|
+        h[:key] = value unless key == :required
+      end
+      h
+    end
   end
 
 end