Commit ed63a5aa authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Merge branch 'master' into esprima-parser

parents 9a1aec05 205b2bf0

README.md

+20 −17
Original line number Diff line number Diff line
@@ -3,13 +3,6 @@ JsDuck 


API documentation generator for Sencha JavaScript frameworks.



           ,~~.

          (  6 )-_,

     (\___ )=='-'

      \ .   ) )

       \ `-' /    hjw

    ~'`~'`~'`~'`~



JsDuck aims to be a better documentation generator for [Ext JS][] than

the old [ext-doc][] was. It is used by Sencha to document [Ext JS

4][ext4-docs], [Sencha Touch][touch2-docs] and [several other][other-docs]
@@ -19,6 +12,10 @@ The highlights of JSDuck are [Markdown][] support and keeping you DRY 
by inferring a lot of information from code.  Read the [Guide][] for

full overview.



**New to JSDuck?** Watch [introductory talk by Nick Poulden][video]:



[<img src="http://b.vimeocdn.com/ts/227/178/227178682_200.jpg" alt="SenchaCon 2011 JSDuck talk" />][video]



[Ext JS]: http://www.sencha.com/products/js/

[ext-doc]: http://ext-doc.org/

[Markdown]: http://daringfireball.net/projects/markdown/
@@ -26,7 +23,7 @@ full overview. 
[touch2-docs]: http://docs.sencha.com/touch/2-0/

[other-docs]: http://docs.sencha.com/ext-js/4-0/

[Guide]: https://github.com/senchalabs/jsduck/wiki/Guide



[video]: http://vimeo.com/33465319



Getting it

----------
@@ -93,19 +90,23 @@ switch. For full list of all command line options type 
[adv]: https://github.com/senchalabs/jsduck/wiki/Advanced-Usage





Hacking it

----------



See [Hacking guide](https://github.com/senchalabs/jsduck/wiki/Hacking) in wiki.





Documenting your code

---------------------



All the supported syntax is described in the [Guide][].

For quick overview take a look at [example.js][example].

For quick overview read the [Guide][] and take a look at [example.js][example].

Follow links in the guide to digg into the details.



Looking for specific @tag? Take a look at the [whole list of supported tags][tags].



[example]: https://github.com/senchalabs/jsduck/blob/master/opt/example.js

[tags]: https://github.com/senchalabs/jsduck/wiki/Tags





Hacking it

----------



See [Hacking guide](https://github.com/senchalabs/jsduck/wiki/Hacking) in wiki.





Copying

-------
@@ -123,7 +124,9 @@ Thanks to [Ondřej Jirman](https://github.com/megous), 
[ligaard](https://github.com/ligaard),

[Bill Hubbard](http://www.sencha.com/forum/member.php?272458-BillHubbard),

[Ed Spencer](https://github.com/edspencer),

[atian25](https://github.com/atian25) and many-many others who

[atian25](https://github.com/atian25),

Katherine Chu,

[Rob Dougan](https://github.com/rdougan) and many-many others who

reported bugs, submitted patches, and provided a lot of useful input.

Rakefile

+88 −101
Original line number Diff line number Diff line
@@ -13,16 +13,16 @@ end 


def load_sdk_vars

  if File.exists?("sdk-vars.rb")

    require "sdk-vars.rb"

    require "./sdk-vars.rb"

  else

    puts "Error: sdk-vars.rb not found."

    puts

    puts "Please create file sdk-vars.rb and define constants SDK_DIR and OUT_DIR in it."

    puts

    puts "For example:"

    puts "Please create file sdk-vars.rb and define in it:"

    puts

    puts "    # path to Ext JS 4 build"

    puts "    EXT_DIR='/path/to/ext-4.0.7'"

    puts "    EXT_BUILD='/path/to/ext-4.0.7'"

    puts "    # path to Touch 2 build"

    puts "    TOUCH_BUILD='/path/to/touch-2.0.0'"

    puts "    # where to output the docs"

    puts "    OUT_DIR='/path/to/ouput/dir'"

    puts "    # path to SDK (for developers at Sencha)"
@@ -127,16 +127,12 @@ def compress 
  system "rm -rf #{dir}/resources/codemirror"

  system "rm -rf #{dir}/resources/.sass-cache"



  # Empty the extjs dir, leave only the main JS files, CSS and images

  # Empty the extjs dir, leave only the main JS file and images

  system "rm -rf #{dir}/extjs"

  system "mkdir #{dir}/extjs"

  system "cp #{EXT_DIR}/ext-all.js #{dir}/extjs"

  system "cp #{EXT_DIR}/ext-all-debug.js #{dir}/extjs"

  system "cp #{EXT_DIR}/bootstrap.js #{dir}/extjs"

  system "mkdir -p #{dir}/extjs/resources/css"

  system "cp #{EXT_DIR}/resources/css/ext-all.css #{dir}/extjs/resources/css"

  system "cp template/extjs/ext-all.js #{dir}/extjs"

  system "mkdir -p #{dir}/extjs/resources/themes/images"

  system "cp -r #{EXT_DIR}/resources/themes/images/default #{dir}/extjs/resources/themes/images"

  system "cp -r #{EXT_BUILD}/resources/themes/images/default #{dir}/extjs/resources/themes/images"

end
@@ -144,49 +140,38 @@ class JsDuckRunner 
  def initialize

    @options = []

    load_sdk_vars

    @sdk_dir = SDK_DIR

    @out_dir = OUT_DIR

    @ext_dir = EXT_DIR

    @animator_dir = ANIMATOR_DIR

  end



  def add_options(options)

    @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

  # same way in both real IE7 and IE7-mode of IE8/9.

  def add_comments(db_name)

  def add_comments(db_name, version)

    comments_base_url = "http://projects.sencha.com/auth"

    @options += ["--head-html", <<-EOHTML]

      <script type="text/javascript">

        Docs.enableComments = ("withCredentials" in new XMLHttpRequest()) || (Ext.ieVersion >= 8);

        Docs.baseUrl = "#{comments_base_url}";

        Docs.commentsDb = "#{db_name}";

        Docs.commentsVersion = "#{version}";

      </script>

    EOHTML

  end



  # For export of ExtJS, reference extjs from the parent dir

  def make_paths_relative

    relative_sdk_path = "../"

    ["#{@out_dir}/eg-iframe.html", "#{@out_dir}/index.html"].each do |file|

  def make_extjs_path_relative

    ["#{OUT_DIR}/index.html"].each do |file|

      out = []

      IO.read(file).each_line do |line|

        out << line.sub(/((src|href)="extjs\/)/, '\2="' + relative_sdk_path)

        out << line.sub(/(src|href)="extjs\//, '\1="../')

      end

      File.open(file, 'w') {|f| f.write(out) }

    end

    system "rm -rf #{OUT_DIR}/extjs"

  end



  def add_ext4
@@ -195,61 +180,19 @@ class JsDuckRunner 
      "--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",

      "--images", "#{EXT_BUILD}/docs/doc-resources",

      "--local-storage-db", "ext-4",

      "--output", "#{@out_dir}",

      "#{@ext_dir}/src",

    ]

  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",

    ]

  end



  def add_touch2_export

    @options += [

      "--export", "full",

      "--output", "#{@out_dir}/../export/touch2",

      "--external=google.maps.Map,google.maps.LatLng",

      "#{@sdk_dir}/touch/touch.jsb3",

      "--output", "#{OUT_DIR}",

      "#{EXT_BUILD}/src",

    ]

  end



  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/eg-iframe.html", "template-min/eg-iframe.html")



    ["template-min/eg-iframe.html", "template-min/welcome.html"].each do |file|

      html = IO.read(file);



      touch_src_re = /((src|href)="touch)/m

      out = []



      html.each_line do |line|

        out << line.sub(/((src|href)="touch\/)/, '\2="' + relative_touch_path)

      end



      File.open(file, 'w') {|f| f.write(out) }

    end



    head_html = <<-EOHTML

  def add_phone_redirect

    @options += ["--body-html", <<-EOHTML]

      <script type="text/javascript">

        Docs.exampleBaseUrl = "#{relative_touch_path}examples/";

        if (Ext.is.Phone) { window.location = "#{relative_touch_path}examples/"; }

        if (Ext.is.Phone) { window.location = "../examples/"; }

      </script>

    EOHTML



    @options += [

      "--body-html", head_html,

      "--welcome", "template-min/welcome.html",

      "--eg-iframe", "template-min/eg-iframe.html"

    ]

  end



  def add_debug
@@ -327,6 +270,10 @@ class JsDuckRunner 
              text: 'Ext JS 3',

              href: 'http://docs.sencha.com/ext-js/3-4'

          },

          {

              text: 'Ext JS 2',

              href: 'http://docs.sencha.com/ext-js/2-3'

          },

          {

              text: 'Sencha Touch 2',

              href: 'http://docs.sencha.com/touch/2-0'
@@ -354,18 +301,13 @@ class JsDuckRunner 


  end



  # Copy over SDK examples

  def copy_sdk_examples

    system "mkdir #{@out_dir}/extjs/builds"

    system "cp #{@ext_dir}/builds/ext-core.js #{@out_dir}/extjs/builds/ext-core.js"

    system "cp #{@ext_dir}/release-notes.html #{@out_dir}/extjs"

    system "cp -r #{@ext_dir}/examples #{@out_dir}/extjs"

    system "cp -r #{@ext_dir}/welcome #{@out_dir}/extjs"

  def copy_extjs_build

    system "cp -r #{EXT_BUILD} #{OUT_DIR}/extjs-build"

  end



  # Copy over Sencha Touch

  def copy_touch2_build

    system "cp -r #{@sdk_dir}/touch/build #{@out_dir}/touch"

    system "cp -r #{TOUCH_BUILD} #{OUT_DIR}/touch"

  end



  def run
@@ -394,11 +336,20 @@ task :sdk, [:mode] => :sass do |t, args| 
  runner.add_seo if mode == "debug" || mode == "live"

  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.add_comments('ext-js', '4') if mode == "debug" || mode == "live"

  if mode == "export"

    runner.add_options ["--eg-iframe", "#{SDK_DIR}/extjs/docs/eg-iframe-build.html"]

    runner.add_options ["--examples-base-url", "../examples/"]

  else

    runner.add_options ["--examples-base-url", "extjs-build/examples/"]

  end

  runner.run



  runner.copy_sdk_examples if mode == "export" || mode == "live"

  runner.make_paths_relative if mode == "export"

  if mode == "export"

    runner.make_extjs_path_relative

  else

    runner.copy_extjs_build

  end

end



desc "Run JSDuck on Docs app itself"
@@ -446,6 +397,23 @@ task :ext3, [:mode] => :sass do |t, args| 
  runner.run

end



desc "Run JSDuck on official Ext JS 2.3 build\n" +

     "ext2             - creates debug/development version\n" +

     "ext2[export]     - creates export/deployable version\n"

     "ext2[live]       - creates live version for deployment\n"

task :ext2, [:mode] => :sass do |t, args|

  mode = args[:mode] || "debug"

  throw "Unknown mode #{mode}" unless ["debug", "export", "live"].include?(mode)

  compress if mode == "export"



  runner = JsDuckRunner.new

  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/../ext-2-source/doc-config.json"]

  runner.add_debug if mode == "debug"

  runner.add_seo if mode == "live"

  runner.add_google_analytics if mode == "live"

  runner.run

end



desc "Run JSDuck on Sencha Touch (for internal use at Sencha)\n" +

     "touch       - creates debug/development version\n" +

     "touch[live] - create live version for deployment\n"
@@ -472,13 +440,26 @@ task :touch2, [:mode] => :sass do |t, args| 
  compress if mode == "live" || mode == "export"



  runner = JsDuckRunner.new

  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/touch/docs/config.json"]

  runner.add_options [

    "--output", OUT_DIR,

    "--config", "#{SDK_DIR}/touch/docs/config.json"

  ]



  if mode == "export"

    runner.add_export_notice("touch/2-0")

    runner.add_phone_redirect

    # override settings in config.json

    runner.add_options [

      "--welcome", "#{SDK_DIR}/touch/docs/build-welcome.html",

      "--eg-iframe", "#{SDK_DIR}/touch/docs/build-eg-iframe.html",

      "--examples-base-url", "../examples/",

    ]

  end



  runner.add_debug if mode == "debug"

  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"

  runner.add_comments('comments-touch-2') if mode == "debug" || mode == "live"

  runner.add_comments('touch', '2') if mode == "debug" || mode == "live"

  runner.run



  runner.copy_touch2_build if mode != "export"
@@ -511,7 +492,7 @@ task :senchaio, [:mode] => :sass do |t, args| 
  compress if mode == "live"



  runner = JsDuckRunner.new

  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/../sync/docs/config.json"]

  runner.add_options ["--output", OUT_DIR, "--config", "#{SDK_DIR}/../client-framework/docs/config.json"]

  runner.add_debug if mode == "debug"

  runner.add_seo if mode == "debug" || mode == "live"

  runner.add_google_analytics if mode == "live"
@@ -532,19 +513,25 @@ task :animator, [:mode] => :sass do |t, args| 
  runner.add_debug if mode == "debug"

  runner.add_seo if mode == "debug" || mode == "live"

  runner.add_google_analytics if mode == "live"

  runner.add_comments('animator', '1') if mode == "debug" || 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)

desc "Run JSDuck on Sencha Designer (for internal use at Sencha)\n" +

     "designer         - creates debug/development version\n" +

     "designer[export] - create live version for deployment\n"

     "designer[live]   - create live version for deployment\n"

task :designer, [:mode] => :sass do |t, args|

  mode = args[:mode] || "debug"

  throw "Unknown mode #{mode}" unless ["debug", "live", "export"].include?(mode)

  compress if mode == "live"



  runner = JsDuckRunner.new

  runner.add_touch_export if mode == "touch"

  runner.add_touch2_export if mode == "touch2"

  runner.add_options ["--output", OUT_DIR, "--config", "#{DESIGNER_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.add_comments('designer', '2') if mode == "debug" || mode == "live"

  runner.run

end

bin/compare

+35 −9
Original line number Diff line number Diff line
@@ -28,15 +28,28 @@ def read_all_classes(dir, ignore_private=false) 
  map

end



def read_ignored_members(filename)

  map = {}

  IO.read(filename).each_line do |line|

    map[line.chomp] = true

  end

  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

def compare_classes(cls1, 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

      if !match && m1["name"] != "constructor" && m1["name"] != ""

      if !match && m1["name"] != "constructor" && m1["name"] != "" && !ignored_members[cls1["name"]+"#"+m1["name"]]

        other = nil

        ["cfg", "property", "method", "event"].each do |g|

          other = other || cls2["members"][g].find {|m2| m2["name"] == m1["name"] }
@@ -59,23 +72,36 @@ def compare_classes(cls1, cls2) 
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) : [],

      :diff => new_cls ? compare_classes(cls, new_cls, ignored_members) : [],

    }

  end

end

jsduck.gemspec

+2 −2
Original line number Diff line number Diff line
@@ -2,8 +2,8 @@ Gem::Specification.new do |s| 
  s.required_rubygems_version = ">= 1.3.5"



  s.name = 'jsduck'

  s.version = '3.3.0'

  s.date = '2012-01-04'

  s.version = '3.8.4'

  s.date = '2012-04-05'

  s.summary = "Simple JavaScript Duckumentation generator"

  s.description = "Documentation generator for Sencha JS frameworks"

  s.homepage = "https://github.com/senchalabs/jsduck"

lib/jsduck/accessors.rb

+1 −6
Original line number Diff line number Diff line
@@ -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",