Merge branch 'master' into sass

rvm:

  - "1.8.7"

  - "1.9.3"

  - "2.0.0"

install:

  - gem install rdiscount

  - gem install json

JSDuck

======

![JSDuck](https://raw.github.com/senchalabs/jsduck/master/opt/jsduck-logo-dark.png)

===================================================================================

[![Build Status](https://travis-ci.org/senchalabs/jsduck.png)](https://travis-ci.org/senchalabs/jsduck)

[<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/

[ext-doc]: http://code.google.com/p/ext-doc/

[Markdown]: http://daringfireball.net/projects/markdown/

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

[touch2-docs]: http://docs.sencha.com/touch/2-0/

[ext4-docs]: http://docs.sencha.com/extjs/

[touch2-docs]: http://docs.sencha.com/touch/

[other-docs]: http://docs.sencha.com/

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

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

    $ [sudo] gem install jsduck

Windows users probably want to [download a binary release][winbin].

Or download the [Windows binary][winbin]. When you run into problems,

see the [installation guide][].

See the [installation guide][] for help when you run into problems.

[winbin]: https://sourceforge.net/projects/jsduck/files/

[winbin]: https://github.com/senchalabs/jsduck/releases

[installation guide]: https://github.com/senchalabs/jsduck/wiki/Installation

Usage

-----

For the simplest test-run just use the `--builtin-classes` option to

automatically produce documentation for JavaScript builtin classes

like Array, String and Object:

    $ jsduck --builtin-classes --output your/docs

write documentation for JavaScript builtin classes like Array, String

and Object into `docs` directory:

You can also use `--verbose` option to see what's actually happening.

    $ jsduck --builtin-classes --output docs

To generate docs for Ext JS 4 add path to the corresponding src/ dir:

To generate docs for [Ext JS 4][] add path to the corresponding src/ dir:

    $ jsduck ext-4.1.1/src \

             --builtin-classes \

             --images ext-4.1.1/docs/images \

             --warnings=-no_doc,-dup_member,-link_ambiguous \

             --external XMLHttpRequest \

             --output your/docs

    $ jsduck ext-4.2.1/src --output docs

The `--images` option specifies a path for images included with

`{@img}` tags inside the source code.

And to create docs for your own Ext JS project, list the directory

with your files in addition to the Ext JS source files (this way the

docs of your classes will list all the properties and methods they

inherit from Ext JS classes):

The `--warnings` option disables some of the warnings which you would

otherwise be overwhelmed with. That's because Ext JS 4.1.1 was

released when JSDuck 4 wasn't out yet.  Sorry for that, JSDuck just

wants to be helpful. Similarly the `--external` option defines

`XMLHttpRequest` as an external class, otherwise a warning would be

thrown.

    $ jsduck ext-4.2.1/src my-project/js --output docs

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`.  For help on a specific option use

`--help=--some-option`.

Unfortunately the above will throw lots of warnings at you, as

building the full Ext JS docs requires lots of additional settings.

For start you might want to simply ignore all these warnings

originating from Ext JS source:

To generate docs for your own project, simply name additional input

directories:

    $ jsduck ext-4.2.1/src my-project/js --output docs \

             --warnings=-all:ext-4.2.1/src

    $ jsduck ext-4.1.1/src project1/js project2/js ...

But see the [Usage guide][] for more information on building Ext JS 4

docs.

Note that the resulting documentation will only contain the API

documentation.  Guides, videos and examples will not be present.

These can be added using more command line options as explained in the

[documentation][].

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

[Usage guide]: https://github.com/senchalabs/jsduck/wiki/Usage

Documenting your code

- Bryntum [Siesta unit testing framework](http://www.bryntum.com/products/siesta/docs/)

- [CKEditor](http://docs.ckeditor.com)

- [GeoExt 2](https://github.com/geoext/geoext2)

- Rally Software [Rally App SDK](https://rally1.rallydev.com/apps/2.0p/doc/)

- Rally Software [Rally App SDK](https://prod.help.rallydev.com/apps/2.0rc1/doc/)

- Wikimedia Foundation [MediaWiki](https://doc.wikimedia.org/mediawiki-core/master/js/)

  and [VisualEditor](https://doc.wikimedia.org/VisualEditor/master/)

- [Sencha](http://docs.sencha.com) - obviously :)

These are some that we know of. Want your project listed here? Drop us a line.

License version 3.

JSDuck was developed by [Rene Saarsoo](http://triin.net),

with many contributions from [Nick Poulden](https://github.com/nick).

Thanks to [Ondřej Jirman](https://github.com/megous),

with contributions from

[Nick Poulden](https://github.com/nick),

[Ondřej Jirman](https://github.com/megous),

[Thomas Aylott](https://github.com/subtleGradient),

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

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

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

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

[Dave Thompson](https://github.com/limscoder),

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

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

Katherine Chu,

[Rob Dougan](https://github.com/rdougan),

[Dave Thompson](https://github.com/limscoder),

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

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

[Chris Westbrook](https://github.com/cnstaging),

[Scott Whittaker](https://github.com/scottrobertwhittaker),

[Timo Tijhof](https://github.com/Krinkle),

and many-many others who reported bugs, submitted patches, and

provided a lot of useful input.

[Brian Moeskau](https://github.com/bmoeskau),

[Garry Yao](https://github.com/garryyao),

[Yasin Okumus](https://github.com/lacivert),

[Nicholas Boll](https://github.com/NicholasBoll) and

Katherine Chu.

Many thanks goes also to those who have most eagerly reported bugs:

[Ryan Nauman](https://github.com/ryan-nauman),

[Raphael Franchet](https://github.com/raphdulaf),

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

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

[Raphael Pigulla](https://github.com/pigulla),

[Dmitry Bakaleinik](https://github.com/demongloom),

[Alan Lindsay](https://github.com/alindsay55661),

[Corey Butler](https://github.com/coreybutler),

[Nickolay Platonov](https://github.com/SamuraiJack),

[Matt Greer](https://github.com/city41),

[Richard](https://github.com/ritcoder) and

[Dmitry Pashkevich](https://github.com/dpashkevich).

There are lots of others I haven't named here, who have provided their

input.

Changelog

---------

See [Changelog](https://github.com/senchalabs/jsduck/wiki/Changelog) page in wiki.

See [the Releases page](https://github.com/senchalabs/jsduck/releases).

More questions?

require 'rspec'

require 'rspec/core/rake_task'

desc "Runs RSpec testsuite (DEFAULT)"

RSpec::Core::RakeTask.new(:spec) do |spec|

  spec.rspec_opts = ["--color"] unless os_is_windows?

  spec.pattern = "spec/**/*_spec.rb"

  system "compass compile --quiet template/resources/sass"

end

def write_version_file(version)

  File.open('./lib/jsduck/version.rb', 'w') do |f|

    f.write(<<-EORUBY)

# This file is updated by rake bump task.

# Do not edit by hand.

module JsDuck

  VERSION = "#{version}"

end

EORUBY

  end

end

def commit_version(version)

  system "git commit lib/jsduck/version.rb -m 'Up version to #{version}.'"

  puts "Creating tag v#{version}"

  system "git tag -a v#{version} -m 'Tagging #{version} release.'"

end

desc <<-EOTEXT

Bumps JSDuck patch version number up by one.

When old version was 1.2.2, new will be 1.2.3.

Alternatively sets the specified version, when invoked like:

    rake bump['1.2.3']

Also commits and tags the change in git.

EOTEXT

task :bump, :new_version do |t, args|

  require "./lib/jsduck/version.rb"

  if args[:new_version]

    new = args[:new_version]

    puts "Bumping version from #{JsDuck::VERSION} to #{new}"

    write_version_file(new)

    commit_version(new)

  else

    if JsDuck::VERSION =~ /\A([0-9]+)\.([0-9]+)\.([0-9]+)\z/

      new = "#{$1}.#{$2}.#{$3.to_i+1}"

      puts "Bumping version from #{JsDuck::VERSION} to #{new}"

      write_version_file(new)

      commit_version(new)

    else

      puts "Unable to automatically bump the version: #{JsDuck::VERSION}"

      exit 1

    end

  end

end

desc "Build JSDuck gem"

task :gem => :sass do

  compress

end

# loops through all members of class

def each_member(cls)

  ["members", "statics"].each do |category|

    cls[category].each_pair do |k, members|

      members.each do |m|

        yield m

      end

    end

  end

def each_member(cls, &block)

  cls["members"].each(&block)

end

def discard_docs(cls)

# Finds equivalent member to given member from class.

# Returns the member found or nil.

def find_member(cls, member)

  cls[member["static"] ? "statics" : "members"][member["tagname"]].find do |m|

  cls["members"].find do |m|

    member["name"] == m["name"]

  end

end

      end

    elsif !m2 && m1["name"] != "constructor" && m1["name"] != ""

      other = nil

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

        other = other || cls2["members"][g].find {|m2| m2["name"] == m1["name"] }

        other = other || cls2["statics"][g].find {|m2| m2["name"] == m1["name"] }

      end

      other = cls2["members"].find {|m2| m2["name"] == m1["name"] }

      diff << {

        :type => m1["tagname"],

        :name => m1["name"],

            html << " (found #{stat} #{priv} #{prot} #{o[:type]} with the same name)"

          elsif m[:changes]

            m[:changes].each do |c|

              html << " (#{c[:what]} changed from #{CGI.escapeHTML(c[:a])} to #{CGI.escapeHTML(c[:b])})"

            end

              html << " (#{c[:what]} changed from #{CGI.escapeHTML(c[:a].to_s)} to #{CGI.escapeHTML(c[:b].to_s)})"

            end

          end

          html << "</li>"

        end

        html << "</ul>"

      end

      html << "</li>"

    end

  elsif cls[:found] == :old

$:.unshift File.dirname(File.dirname(__FILE__)) + "/lib"

require 'jsduck/app'

require 'jsduck/options'

require 'jsduck/options/processor'

opts = JsDuck::Options::Processor.process(ARGV)

opts = JsDuck::Options.new

opts.parse!(ARGV)

exit_code = JsDuck::App.new(opts).run

exit exit_code