jsduck 0.1

data/README.md

@@ -0,0 +1,197 @@
+JsDuck
+======
+
+Simple JavaScript Duckumentation generator.
+
+           ,~~.
+          (  6 )-_,
+     (\___ )=='-'
+      \ .   ) )
+       \ `-' /    hjw
+    ~'`~'`~'`~'`~
+
+JsDuck aims to be a better documentation generator for [ExtJS][].
+While it tries to do everything that [ext-doc][] does, it isn't
+satisfied with it and aims to make your life much easier.
+
+Basically JsDuck thinks that the following doc-comment really sucks:
+
+    /**
+     * @class Ext.form.TextField
+     * @extends Ext.form.Field
+     * <p>Basic text field.  Can be used as a direct replacement for traditional
+     * text inputs, or as the base class for more sophisticated input controls
+     * (like {@link Ext.form.TextArea} and {@link Ext.form.ComboBox}).</p>
+     * <p><b><u>Validation</u></b></p>
+     * <p>The validation procedure is described in the documentation for
+     * {@link #validateValue}.</p>
+     * <p><b><u>Alter Validation Behavior</u></b></p>
+     * <p>Validation behavior for each field can be configured:</p>
+     * <div class="mdetail-params"><ul>
+     * <li><code>{@link Ext.form.TextField#invalidText invalidText}</code> :
+     * the default validation message to show if any validation step above does
+     * not provide a message when invalid</li>
+     * <li><code>{@link Ext.form.TextField#maskRe maskRe}</code> :
+     * filter out keystrokes before any validation occurs</li>
+     * <li><code>{@link Ext.form.TextField#stripCharsRe stripCharsRe}</code> :
+     * filter characters after being typed in, but before being validated</li>
+     * </ul></div>
+     *
+     * @constructor Creates a new TextField
+     * @param {Object} config Configuration options
+     *
+     * @xtype textfield
+     */
+    Ext.form.TextField = Ext.extend(Ext.form.Field,  {
+
+Not quite so readable is it?  The source of ExtJS is filled with
+comments just like that, and when you use ext-doc, you too are forced
+to write such comments.
+
+JsDuck does not like it.  Although it can handle comments like this,
+it would like that you wrote comments like that instead:
+
+    /**
+     * Basic text field.  Can be used as a direct replacement for traditional
+     * text inputs, or as the base class for more sophisticated input controls
+     * (like {@link Ext.form.TextArea} and {@link Ext.form.ComboBox}).
+     *
+     * Validation
+     * ----------
+     *
+     * The validation procedure is described in the documentation for
+     * {@link #validateValue}.
+     *
+     * Alter Validation Behavior
+     * -------------------------
+     *
+     * Validation behavior for each field can be configured:
+     *
+     * - `{@link Ext.form.TextField#invalidText invalidText}` :
+     *   the default validation message to show if any validation step above
+     *   does not provide a message when invalid
+     * - `{@link Ext.form.TextField#maskRe maskRe}` :
+     *   filter out keystrokes before any validation occurs
+     * - `{@link Ext.form.TextField#stripCharsRe stripCharsRe}` :
+     *   filter characters after being typed in, but before being validated
+     *
+     * @xtype textfield
+     */
+    Ext.form.TextField = Ext.extend(Ext.form.Field,  {
+
+As you can see, JsDuck supports formatting comments with friendly
+[Markdown][] syntax.  And it can infer several things from the code
+(like @class and @extends in this case), so you don't have to repeat
+yourself.  Also the constructor documentation is inherited from parent
+class - so you don't have to restate that it takes a config object
+again.
+
+That's basically it.  Have fun.
+
+[ExtJS]: http://www.sencha.com/products/js/
+[ext-doc]: http://ext-doc.org/
+[Markdown]: http://daringfireball.net/projects/markdown/
+
+
+Getting it
+----------
+
+Standard rubygems install should do:
+
+    $ [sudo] gem install jsduck
+
+For hacking fork it from github.
+
+    $ git clone git://github.com/nene/jsduck.git
+    $ cd jsduck
+    $ rake --tasks
+
+JsDuck depends on [json][] and [RDiscount][] plus [RSpec][] for tests.
+
+[json]: http://flori.github.com/json/
+[RDiscount]: https://github.com/rtomayko/rdiscount
+[RSpec]: http://rspec.info/
+
+
+Usage
+-----
+
+Just call it from command line with output directory and a list of
+JavaScript files:
+
+    $ jsduck --verbose --output some/dir  your/project/*.js
+
+To specify a lot of files you should probably create a script that
+generates a file list and passes it through `xargs` to `jsduck`.
+
+For example to generate documentation for ExtJS:
+
+    $ find ext-3.3.1/src/ -name '*.js' | egrep -v 'locale/|test/|adapter/' | xargs jsduck -v -o output/
+
+The `--verbose` flag creates a lot of output, but at least you will
+see that something is happening.
+
+Here's how the resulting documentation will look:
+
+* [JsDuck generated documentation](http://triin.net/temp/jsduck/)
+* [Official ExtJS documentation](http://dev.sencha.com/deploy/dev/docs/) (for comparison)
+
+
+Documentation
+-------------
+
+Overview of documenting your code with JsDuck:
+
+* [Class](https://github.com/nene/jsduck/wiki/Class)
+* [Constructor](https://github.com/nene/jsduck/wiki/Constructor)
+* [Config options](https://github.com/nene/jsduck/wiki/Cfg)
+* [Properties](https://github.com/nene/jsduck/wiki/Property)
+* [Methods](https://github.com/nene/jsduck/wiki/Method)
+* [Events](https://github.com/nene/jsduck/wiki/Event)
+
+More details:
+
+* [List of supported @tags][tags]
+* [List of doc-comment errors(?) found in ExtJS source][errors]
+
+[tags]: https://github.com/nene/jsduck/wiki/List-of-supported-@tags
+[errors]: https://github.com/nene/jsduck/wiki/List-of-doc-comment-errors(%3F)-found-in-ExtJS-source
+
+
+Features and differences from ext-doc
+-------------------------------------
+
+JsDuck has some strong opinions, so some things are intentionally
+missing.
+
+* Support for Markdown in comments
+* More things infered from the code
+* No XML configuration file, just command line options
+* Class documentation header doesn't separately list Package and Class -
+  these are IMHO redundant.
+* Class documentation header doesn't duplicate toolbar buttons -
+  another redundancy
+* Ext.Component has a component icon too, not only its descendants
+
+
+Missing features
+----------------
+
+It's still in early beta, so several things supported by ext-doc are
+currently missing:
+
+* Links from documentation to source code
+* List of subclasses
+* Tree of parent classes
+* Syntax highlighting of code examples
+* Search, not just searching from official ExtJS documentation
+* Support for custom @tags
+
+
+Copying
+-------
+
+JsDuck is distributed under the terms of the GNU General Public License version 3.
+
+JsDuck was developed by [Rene Saarsoo](http://triin.net).
+

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'rake'
+
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+require 'spec'
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.spec_opts = ["--color"]
+  spec.spec_files = FileList["spec/**/*_spec.rb"]
+end
+
+desc "Build gem locally"
+task :build do
+  system "gem build jsduck.gemspec"
+end
+
+desc "Install gem locally"
+task :install => :build do
+  system "gem install --user-install jsduck"
+end
+
+task :default => :spec

data/bin/jsduck

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# JsDuck is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# JsDuck is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with JsDuck.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Copyright 2010 Rene Saarsoo.
+
+# For running when gem not installed
+$:.unshift File.dirname(File.dirname(__FILE__)) + "/lib"
+
+require 'jsduck/app'
+require 'optparse'
+
+app = JsDuck::App.new
+app.template_dir = File.dirname(File.dirname(__FILE__)) + "/template"
+
+opts = OptionParser.new do | opts |
+  opts.banner = "Usage: jsduck [options] files..."
+
+  opts.on('-o', '--output=PATH', "Directory to output all this amazing documentation.") do |path|
+    app.output_dir = path
+  end
+
+  opts.on('-t', '--template=PATH', "Directory containing doc-browser UI template.") do |path|
+    app.template_dir = path
+  end
+
+  opts.on('-v', '--verbose', "This will fill up your console.") do
+    app.verbose = true
+  end
+
+  opts.on('-h', '--help', "Prints this help message") do
+    puts opts
+    exit
+  end
+end
+
+app.input_files = opts.parse!(ARGV)
+
+if app.input_files.length == 0
+  puts "You should specify some input files, otherwise there's nothing I can do :("
+  exit(1)
+elsif !app.output_dir
+  puts "You should also specify an output directory, where I could write all this amazing documentation."
+  exit(1)
+elsif File.exists?(app.output_dir) && !File.directory?(app.output_dir)
+  puts "Oh noes!  The output directory is not really a directory at all :("
+  exit(1)
+elsif !File.exists?(File.dirname(app.output_dir))
+  puts "Oh noes!  The parent directory for #{output_dir} doesn't exist."
+  exit(1)
+end
+
+app.run()

data/jsduck.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.required_rubygems_version = ">= 1.3.7"
+
+  s.name = 'jsduck'
+  s.version = '0.1'
+  s.date = '2010-12-27'
+  s.summary = "Simple JavaScript Duckumentation generator"
+  s.description = "Better ext-doc like JavaScript documentation generator for ExtJS"
+  s.homepage = "https://github.com/nene/jsduck"
+  s.authors = ["Rene Saarsoo"]
+  s.email = "nene@triin.net"
+  s.rubyforge_project = s.name
+
+  s.files = `git ls-files`.split("\n").find_all {|file| file !~ /spec.rb$/ }
+  s.executables = ["jsduck"]
+
+  s.add_dependency 'rdiscount'
+  s.add_dependency 'json'
+
+  s.require_path = 'lib'
+end

data/lib/jsduck/aggregator.rb

@@ -0,0 +1,104 @@
+require 'jsduck/parser'
+require 'jsduck/doc_parser'
+require 'jsduck/merger'
+
+module JsDuck
+
+  # Combines JavaScript Parser, DocParser and Merger.
+  # Produces array of classes as result.
+  class Aggregator
+    def initialize
+      @documentation = []
+      @classes = {}
+      @orphans = []
+      @current_class = nil
+      @doc_parser = DocParser.new
+      @merger = Merger.new
+    end
+
+    def parse(input)
+      @current_class = nil
+      Parser.new(input).parse.each do |docset|
+        doc = @doc_parser.parse(docset[:comment])
+        code = docset[:code]
+        register(@merger.merge(doc, code))
+      end
+    end
+
+    # Registers documentation node either as class or as member of
+    # some class.
+    def register(node)
+      if node[:tagname] == :class
+        add_class(node)
+      else
+        add_member(node)
+      end
+    end
+
+    # When class exists, merge it with class node.
+    # Otherwise add as new class.
+    def add_class(cls)
+      old_cls = @classes[cls[:name]]
+      if old_cls
+        merge_classes(old_cls, cls)
+        @current_class = old_cls
+      else
+        @current_class = cls
+        @documentation << cls
+        @classes[cls[:name]] = cls
+        insert_orphans(cls)
+      end
+    end
+
+    # Merges new class-doc into old one.
+    def merge_classes(old, new)
+      [:extends, :xtype, :singleton, :private].each do |tag|
+        old[tag] = old[tag] || new[tag]
+      end
+      old[:doc] = old[:doc].length > 0 ? old[:doc] : new[:doc]
+      old[:cfg] = old[:cfg] + new[:cfg]
+    end
+
+    # Tries to place members into classes where they belong.
+    #
+    # @member explicitly defines the containing class, but we can meet
+    # item with @member=Foo before we actually meet class Foo - in
+    # that case we register them as orphans.  (Later when we finally
+    # meet class Foo, orphans are inserted into it.)
+    #
+    # Items without @member belong by default to the preceding class.
+    # When no class precedes them - they too are orphaned.
+    def add_member(node)
+      if node[:member]
+        if @classes[node[:member]]
+          @classes[node[:member]][node[:tagname]] << node
+        else
+          add_orphan(node)
+        end
+      elsif @current_class
+        node[:member] = @current_class[:name]
+        @current_class[ node[:tagname] ] << node
+      else
+        add_orphan(node)
+      end
+    end
+
+    def add_orphan(node)
+      @orphans << node
+    end
+
+    # Inserts available orphans to class
+    def insert_orphans(cls)
+      members = @orphans.find_all {|node| node[:member] == cls[:name] }
+      members.each do |node|
+        cls[node[:tagname]] << node
+        @orphans.delete(node)
+      end
+    end
+
+    def result
+      @documentation + @orphans
+    end
+  end
+
+end

data/lib/jsduck/app.rb

@@ -0,0 +1,89 @@
+require 'rubygems'
+require 'jsduck/aggregator'
+require 'jsduck/class'
+require 'jsduck/tree'
+require 'jsduck/tree_icons'
+require 'jsduck/page'
+require 'json'
+require 'fileutils'
+
+module JsDuck
+
+  # The main application logic of jsduck
+  class App
+    # These are basically input parameters for app
+    attr_accessor :output_dir
+    attr_accessor :template_dir
+    attr_accessor :input_files
+    attr_accessor :verbose
+
+    def initialize
+      @output_dir = nil
+      @template_dir = nil
+      @input_files = []
+      @verbose = false
+    end
+
+    # Call this after input parameters set
+    def run
+      classes = filter_classes(parse_files(@input_files))
+      copy_template(@template_dir, @output_dir)
+      write_tree(@output_dir+"/output/tree.js", classes)
+      write_pages(@output_dir+"/output", classes)
+    end
+
+    # Given array of filenames, parses all files and returns array of
+    # documented items in all of those files.
+    def parse_files(filenames)
+      agr = Aggregator.new
+      filenames.each do |name|
+        puts "Parsing #{name} ..." if @verbose
+        agr.parse(IO.read(name))
+      end
+      agr.result
+    end
+
+    # Filters out class-documentations, converting them to Class objects.
+    # For each other type, prints a warning message and discards it
+    def filter_classes(docs)
+      classes = {}
+      docs.each do |d|
+        if d[:tagname] == :class
+          classes[d[:name]] = Class.new(d, classes)
+        else
+          puts "Warning: Ignoring " + d[:tagname].to_s + ": " + (d[:name] || "")
+        end
+      end
+      classes.values
+    end
+
+    # Given array of doc-objects, generates namespace tree and writes in
+    # in JSON form into a file.
+    def write_tree(filename, docs)
+      tree = Tree.new.create(docs)
+      icons = TreeIcons.new.extract_icons(tree)
+      js = "Docs.classData = " + JSON.generate( tree ) + ";"
+      js += "Docs.icons = " + JSON.generate( icons ) + ";"
+      File.open(filename, 'w') {|f| f.write(js) }
+    end
+
+    # Writes documentation page for each class
+    def write_pages(path, docs)
+      docs.each do |cls|
+        filename = path + "/" + cls[:name] + ".html"
+        puts "Writing to #{filename} ..." if @verbose
+        File.open(filename, 'w') {|f| f.write( Page.new(cls).to_html ) }
+      end
+    end
+
+    def copy_template(template_dir, dir)
+      puts "Copying template files to #{dir}..." if @verbose
+      if File.exists?(dir)
+        FileUtils.rm_r(dir)
+      end
+      FileUtils.cp_r(template_dir, dir)
+      FileUtils.mkdir(dir + "/output")
+    end
+  end
+
+end