jsduck 0.1

data/lib/jsduck/method_table.rb

@@ -0,0 +1,45 @@
+require 'jsduck/table'
+require 'jsduck/short_params'
+require 'jsduck/long_params'
+
+module JsDuck
+
+  class MethodTable < Table
+    def initialize(cls)
+      super(cls)
+      @type = :method
+      @id = @cls.full_name + "-methods"
+      @title = "Public Methods"
+      @column_title = "Method"
+      @row_class = "method-row"
+      @short_params = ShortParams.new
+      @long_params = LongParams.new(@cls)
+    end
+
+    def signature_suffix(item)
+      @short_params.render(item[:params]) + " : " + item[:return][:type]
+    end
+
+    def extra_doc(item)
+      [
+        "<div class='mdetail-params'>",
+        "<strong>Parameters:</strong>",
+        @long_params.render(item[:params]),
+        "<strong>Returns:</strong>",
+        render_return(item),
+        "</div>"
+      ].join("\n")
+    end
+
+    def render_return(item)
+      type = item[:return][:type]
+      doc = item[:return][:doc]
+      if type == "void" && doc.length == 0
+        "<ul><li>void</li></ul>"
+      else
+        "<ul><li><code>#{type}</code><div class='sub-desc'>#{doc}</div></li></ul>"
+      end
+    end
+  end
+
+end

data/lib/jsduck/page.rb

@@ -0,0 +1,56 @@
+require 'jsduck/doc_formatter'
+require 'jsduck/cfg_table'
+require 'jsduck/property_table'
+require 'jsduck/method_table'
+require 'jsduck/event_table'
+
+module JsDuck
+
+  # Creates HTML documentation page for one class.
+  class Page
+    def initialize(cls)
+      @cls = cls
+      @formatter = DocFormatter.new(cls.full_name)
+    end
+
+    def to_html
+      [
+       '<div class="body-wrap">',
+       heading,
+       abstract,
+       description,
+       "<div class='hr'></div>",
+       CfgTable.new(@cls).to_html,
+       PropertyTable.new(@cls).to_html,
+       MethodTable.new(@cls).to_html,
+       EventTable.new(@cls).to_html,
+       "</div>",
+      ].join("\n")
+    end
+
+    def heading
+      "<h1>Class <a href='source/sample.html#cls-#{@cls.full_name}'>#{@cls.full_name}</a></h1>"
+    end
+
+    def abstract
+      [
+       "<table cellspacing='0'>",
+        abstract_row("Extends:", @cls.parent ? class_link(@cls.parent.full_name) : "Object"),
+       "</table>",
+      ].join("\n")
+    end
+
+    def class_link(name)
+      "<a href='output/#{name}.html' ext:cls='#{name}'>#{name}</a>"
+    end
+
+    def abstract_row(label, info)
+      "<tr><td class='label'>#{label}</td><td class='hd-info'>#{info}</td></tr>"
+    end
+
+    def description
+      "<div class='description'>#{@formatter.format(@cls[:doc])}</div>"
+    end
+  end
+
+end

data/lib/jsduck/parser.rb

@@ -0,0 +1,195 @@
+require 'jsduck/lexer'
+
+module JsDuck
+
+  class Parser
+    def initialize(input)
+      @lex = Lexer.new(input)
+      @docs = []
+    end
+
+    # Parses the whole JavaScript block and returns array where for
+    # each doc-comment there is a hash of two values: the comment
+    # itself as string and parsed structure of the code that
+    # immediately follows the comment.
+    #
+    # For example with the following JavaScript input:
+    #
+    # /**
+    #  * @param {String} foo
+    #  */
+    # MyClass.doIt = function(foo, bar) {
+    # }
+    #
+    # The return value of this function will be:
+    #
+    # [
+    #   {
+    #     :comment => "/**\n * @param {String} foo\n */",
+    #     :code => {
+    #       :type => :assignment,
+    #       :left => ["MyClass", "doIt"],
+    #       :right => {
+    #         :type => :function,
+    #         :name => nil,
+    #         :params => [
+    #           {:name => "foo"},
+    #           {:name => "bar"}
+    #         ]
+    #       }
+    #     }
+    #   }
+    # ]
+    #
+    def parse
+      while !@lex.empty? do
+        if look(:doc_comment) then
+          @docs << {
+            :comment => match(:doc_comment),
+            :code => code_block
+          }
+        else
+          @lex.next
+        end
+      end
+      @docs
+    end
+
+    # The following is a recursive-descent parser for JavaScript that
+    # can possibly follow a doc-comment
+
+    # <code-block> := <function> | <var-declaration> | <assignment> | <property-literal>
+    def code_block
+      if look("function") then
+        function
+      elsif look("var") then
+        var_declaration
+      elsif look(:ident, ":") || look(:string, ":") then
+        property_literal
+      elsif look(:ident) || look("this") then
+        maybe_assignment
+      elsif look(:string) then
+        {:type => :assignment, :left => [match(:string)]}
+      else
+        {:type => :nop}
+      end
+    end
+
+    # <function> := "function" [ <ident> ] <function-parameters> <function-body>
+    def function
+      match("function")
+      return {
+        :type => :function,
+        :name => look(:ident) ? match(:ident) : nil,
+        :params => function_parameters,
+        :body => function_body,
+      }
+    end
+
+    # <function-parameters> := "(" [ <ident> [ "," <ident> ]* ] ")"
+    def function_parameters
+      match("(")
+      params = look(:ident) ? [{:name => match(:ident)}] : []
+      while look(",", :ident) do
+        params << {:name => match(",", :ident)}
+      end
+      match(")")
+      return params
+    end
+
+    # <function-body> := "{" ...
+    def function_body
+      match("{")
+    end
+
+    # <var-declaration> := "var" <assignment>
+    def var_declaration
+      match("var")
+      maybe_assignment
+    end
+
+    # <maybe-assignment> := <ident-chain> [ "=" <expression> ]
+    def maybe_assignment
+      left = ident_chain
+      if look("=") then
+        match("=")
+        right = expression
+      end
+      return {
+        :type => :assignment,
+        :left => left,
+        :right => right,
+      }
+    end
+
+    # <ident-chain> := [ "this" | <ident> ]  [ "." <ident> ]*
+    def ident_chain
+      if look("this")
+        chain = [match("this")]
+      else
+        chain = [match(:ident)]
+      end
+
+      while look(".", :ident) do
+        chain << match(".", :ident)
+      end
+      return chain
+    end
+
+    # <expression> := <function> | <ext-extend> | <literal>
+    # <literal> := <string> | <boolean> | <number> | <regex>
+    def expression
+      if look("function") then
+        function
+      elsif look("Ext", ".", "extend") then
+        ext_extend
+      elsif look(:string) then
+        {:type => :literal, :class => "String"}
+      elsif look("true") || look("false") then
+        {:type => :literal, :class => "Boolean"}
+      elsif look(:number) then
+        {:type => :literal, :class => "Number"}
+      elsif look(:regex) then
+        {:type => :literal, :class => "RegExp"}
+      end
+    end
+
+    # <ext-extend> := "Ext" "." "extend" "(" <ident-chain> "," ...
+    def ext_extend
+      match("Ext", ".", "extend", "(")
+      return {
+        :type => :ext_extend,
+        :extend => ident_chain,
+      }
+    end
+
+    # <property-literal> := ( <ident> | <string> ) ":" <expression>
+    def property_literal
+      left = look(:ident) ? match(:ident) : match(:string)
+      match(":")
+      right = expression
+      return {
+        :type => :assignment,
+        :left => [left],
+        :right => right,
+      }
+    end
+
+    # Matches all arguments, returns the value of last match
+    # When the whole sequence doesn't match, throws exception
+    def match(*args)
+      if look(*args) then
+        last = nil
+        args.length.times { last = @lex.next }
+        last
+      else
+        throw "Expected: " + args.join(", ")
+      end
+    end
+
+    def look(*args)
+      @lex.look(*args)
+    end
+  end
+
+end

data/lib/jsduck/property_table.rb

@@ -0,0 +1,21 @@
+require 'jsduck/table'
+
+module JsDuck
+
+  class PropertyTable < Table
+    def initialize(cls)
+      super(cls)
+      @type = :property
+      @id = @cls.full_name + "-props"
+      @title = "Public Properties"
+      @column_title = "Property"
+      @row_class = "property-row"
+    end
+
+    def signature_suffix(item)
+      " : " + item[:type]
+    end
+
+  end
+
+end

data/lib/jsduck/short_params.rb

@@ -0,0 +1,28 @@
+module JsDuck
+
+  # Renders method/event parameters list in short form
+  # for use in signatures
+  class ShortParams
+    def render(params)
+      if params.length > 0
+        "( " + params.collect {|p| render_single(p) }.join(", ") + " )"
+      else
+        "()"
+      end
+    end
+
+    def render_single(param)
+      str = "<code>#{param[:type]} #{param[:name]}</code>"
+      if optional?(param)
+        "<span title='Optional' class='optional'>[" + str + "]</span>"
+      else
+        str
+      end
+    end
+
+    def optional?(param)
+      return param[:doc] =~ /\(optional\)/
+    end
+  end
+
+end

data/lib/jsduck/table.rb

@@ -0,0 +1,109 @@
+require 'jsduck/doc_formatter'
+
+module JsDuck
+
+  # Base class for creating HTML tables of class members.
+  #
+  # Subclasses must set variables @type, @id, @title, @column_title,
+  # @row_class, and implement the signature_suffix() and extra_doc()
+  # methods.
+  class Table
+    def initialize(cls)
+      @cls = cls
+      @formatter = DocFormatter.new(cls.full_name)
+    end
+
+    def to_html
+      rows = @cls.members(@type).collect {|m| row(m) }
+
+      # When no rows to show, create no table whatsoever
+      return "" if rows.length == 0
+
+      [
+       "<a id='#{@id}'></a>",
+       "<h2>#{@title}</h2>",
+       "<table cellspacing='0' class='member-table'><tbody>",
+       "<tr><th colspan='2' class='sig-header'>#{@column_title}</th><th class='msource-header'>Defined By</th></tr>",
+       rows.join("\n"),
+       "</tbody></table>",
+      ].join("\n")
+    end
+
+    def row(item)
+      p_doc = primary_doc(item)
+      e_doc = extra_doc(item)
+      description = expandable_desc(p_doc, e_doc)
+      expandable = expandable?(p_doc, e_doc) ? 'expandable' : ''
+      inherited = inherited?(item) ? 'inherited' : ''
+      source = inherited?(item) ? member_link(item) : Class.short_name(item[:member])
+      [
+       "<tr class='#{@row_class} #{expandable} #{inherited}'>",
+         "<td class='micon'><a href='#expand' class='exi'>&nbsp;</a></td>",
+         "<td class='sig'>#{signature(item)}<div class='mdesc'>#{description}</div></td>",
+         "<td class='msource'>#{source}</td>",
+       "</tr>",
+      ].join("")
+    end
+
+    def member_link(item)
+      cls = item[:member]
+      member = item[:name]
+      "<a href='output/#{cls}.html##{member}' " +
+        "ext:member='##{member}' " +
+        "ext:cls='#{cls}'>#{Class.short_name(cls)}</a>"
+    end
+
+    def signature(item)
+      id = @cls.full_name+ "-" + item[:name]
+      src = "source/sample.html#" + id
+      return "<a id='#{id}'></a><b><a href='#{src}'>#{item[:name]}</a></b>" + signature_suffix(item)
+    end
+
+    # 116 chars is also where ext-doc makes its cut, but unlike
+    # ext-doc we only make the cut when there's more than 120 chars.
+    #
+    # This way we don't get stupid expansions like:
+    #
+    #   Blah blah blah some text...
+    #
+    # expanding to:
+    #
+    #   Blah blah blah some text.
+    #
+    def expandable_desc(p_doc, e_doc)
+      if expandable?(p_doc, e_doc)
+        # Only show ellipsis when primary_doc is shortened.
+        tagless = strip_tags(p_doc)
+        short_doc = tagless[0..116]
+        ellipsis = tagless.length > short_doc.length ? "..." : ""
+        "<div class='short'>#{short_doc}#{ellipsis}</div>" +
+          "<div class='long'>#{p_doc}#{e_doc}</div>"
+      else
+        p_doc
+      end
+    end
+
+    def primary_doc(item)
+      @formatter.format(item[:doc])
+    end
+
+    # Override to append extra documentation to the doc found in item[:doc]
+    def extra_doc(item)
+      ""
+    end
+
+    def expandable?(p_doc, e_doc)
+      strip_tags(p_doc).length > 120 || e_doc.length > 0
+    end
+
+    def strip_tags(str)
+      str.gsub(/<.*?>/, "")
+    end
+
+    def inherited?(item)
+      item[:member] != @cls.full_name
+    end
+
+  end
+
+end