jsduck 0.5 → 0.6

data/lib/jsduck/long_params.rb

@@ -1,15 +1,10 @@
-require "jsduck/doc_formatter"
-
 module JsDuck
 
   # Renders method/event parameters list in long form
   # for use in documentation body.
   class LongParams
-    def initialize(cls)
-      @formatter = DocFormatter.new()
-      @formatter.context = cls.full_name
-      @formatter.css_class = 'docClass'
-      @formatter.url_template = 'output/%cls%.html'
+    def initialize(formatter)
+      @formatter = formatter
     end
 
     def render(params)
@@ -22,9 +17,10 @@ module JsDuck
 
     def render_single(param)
       doc = @formatter.format(param[:doc])
+      type = @formatter.replace(param[:type])
       return [
         "<li>",
-        "<code>#{param[:name]}</code> : #{param[:type]}",
+        "<code>#{param[:name]}</code> : #{type}",
         "<div class='sub-desc'>#{doc}</div>",
         "</li>",
       ].join("")

data/lib/jsduck/members.rb

@@ -9,15 +9,29 @@ module JsDuck
     def create(docs)
       list = []
       docs.each do |cls|
+        list << class_node(cls)
         [:cfg, :property, :method, :event].each do |type|
           cls.members(type).each do |m|
-            list << member_node(m, cls)
+            # skip inherited items and constructors
+            if m[:member] == cls.full_name && m[:name] != cls.short_name
+              list << member_node(m, cls)
+            end
           end
         end
       end
       list
     end
 
+    # Creates structure representing one class
+    def class_node(cls)
+      return {
+        :cls => cls.full_name,
+        :member => cls.short_name,
+        :type => :cls,
+        :doc => short_desc(cls[:doc])
+      }
+    end
+
     # Creates structure representing one member
     def member_node(member, cls)
       return {

data/lib/jsduck/merger.rb

@@ -18,6 +18,10 @@ module JsDuck
         create_cfg(docs, code)
       when :property
         create_property(docs, code)
+      when :css_var
+        create_css_var(docs, code)
+      when :css_mixin
+        create_css_mixin(docs, code)
       end
     end
 
@@ -33,12 +37,16 @@ module JsDuck
         :method
       elsif doc_map[:property] || doc_map[:type]
         :property
+      elsif doc_map[:css_var]
+        :css_var
       elsif code[:type] == :ext_define
         :class
       elsif code[:type] == :assignment && class_name?(*code[:left])
         :class
       elsif code[:type] == :function && class_name?(code[:name])
         :class
+      elsif code[:type] == :css_mixin
+        :css_mixin
       elsif doc_map[:cfg]
         :cfg
       elsif code[:type] == :function
@@ -67,6 +75,8 @@ module JsDuck
       end
       result[:property] = []
       result[:event] = []
+      result[:css_var] = []
+      result[:css_mixin] = []
       result
     end
 
@@ -109,9 +119,11 @@ module JsDuck
         :name => detect_name(:class, doc_map, code, :full_name),
         :doc => detect_doc(docs),
         :extends => detect_extends(doc_map, code),
-        :mixins => detect_mixins(doc_map, code),
+        :mixins => detect_list(:mixins, doc_map, code),
+        :alternateClassNames => detect_list(:alternateClassNames, doc_map, code),
         :xtype => detect_xtype(doc_map),
         :author => detect_author(doc_map),
+        :docauthor => detect_docauthor(doc_map),
         :singleton => !!doc_map[:singleton],
         :private => !!doc_map[:private],
       }
@@ -168,13 +180,39 @@ module JsDuck
       }
     end
 
+    def create_css_var(docs, code)
+      doc_map = build_doc_map(docs)
+      return {
+        :tagname => :css_var,
+        :name => detect_name(:css_var, doc_map, code),
+        :member => detect_member(doc_map),
+        :type => detect_type(:css_var, doc_map, code),
+        :doc => detect_doc(docs),
+        :private => !!doc_map[:private],
+        :static => !!doc_map[:static],
+      }
+    end
+
+    def create_css_mixin(docs, code)
+      doc_map = build_doc_map(docs)
+      return {
+        :tagname => :css_mixin,
+        :name => detect_name(:css_mixin, doc_map, code),
+        :member => detect_member(doc_map),
+        :doc => detect_doc(docs),
+        :params => detect_params(docs, code),
+        :private => !!doc_map[:private],
+        :static => !!doc_map[:static],
+      }
+    end
+
     def detect_name(tagname, doc_map, code, name_type = :last_name)
       main_tag = doc_map[tagname] ? doc_map[tagname].first : {}
       if main_tag[:name]
         main_tag[:name]
       elsif doc_map[:constructor]
         "constructor"
-      elsif code[:type] == :function
+      elsif code[:type] == :function || code[:type] == :css_mixin
         code[:name]
       elsif code[:type] == :assignment
         name_type == :full_name ? code[:left].join(".") : code[:left].last
@@ -224,9 +262,12 @@ module JsDuck
       end
     end
 
-    def detect_mixins(doc_map, code)
-      if code[:type] == :ext_define && code[:mixins]
-        code[:mixins]
+    # for detecting mixins and alternateClassNames
+    def detect_list(type, doc_map, code)
+      if doc_map[type]
+        doc_map[type].map {|d| d[type] }.flatten
+      elsif code[:type] == :ext_define && code[type]
+        code[type]
       else
         []
       end
@@ -240,6 +281,10 @@ module JsDuck
       doc_map[:author] ? doc_map[:author].first[:name] : nil
     end
 
+    def detect_docauthor(doc_map)
+      doc_map[:docauthor] ? doc_map[:docauthor].first[:name] : nil
+    end
+
     def detect_params(docs, code)
       implicit = detect_implicit_params(code)
       explicit = detect_explicit_params(docs)

data/lib/jsduck/method_table.rb

@@ -5,19 +5,15 @@ require 'jsduck/long_params'
 module JsDuck
 
   class MethodTable < Table
-    def initialize(cls, cache={})
-      super(cls, cache)
+    def initialize(cls, formatter, cache={})
+      super(cls, formatter, cache)
       @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)
-      @formatter = DocFormatter.new()
-      @formatter.context = @cls.full_name
-      @formatter.css_class = 'docClass'
-      @formatter.url_template = 'output/%cls%.html'
+      @long_params = LongParams.new(@formatter)
     end
 
     def signature_suffix(item)
@@ -36,7 +32,7 @@ module JsDuck
     end
 
     def render_return(item)
-      type = item[:return][:type]
+      type = @formatter.replace(item[:return][:type])
       doc = @formatter.format(item[:return][:doc])
       if type == "void" && doc.length == 0
         "<ul><li>void</li></ul>"

data/lib/jsduck/page.rb

@@ -1,3 +1,4 @@
+require 'cgi'
 require 'jsduck/doc_formatter'
 require 'jsduck/inheritance_tree'
 require 'jsduck/cfg_table'
@@ -21,8 +22,16 @@ module JsDuck
       @cache = cache
       @formatter = DocFormatter.new
       @formatter.context = cls.full_name
-      @formatter.css_class = 'docClass'
-      @formatter.url_template = 'output/%cls%.html'
+      @formatter.link_tpl = '<a href="output/%c.html%M" rel="%c%M" class="docClass">%a</a>'
+      @formatter.relations = relations
+    end
+
+    # Setters to override link and image templates
+    def link_tpl=(tpl)
+      @formatter.link_tpl = tpl
+    end
+    def img_tpl=(tpl)
+      @formatter.img_tpl = tpl
     end
 
     def to_html
@@ -33,17 +42,17 @@ module JsDuck
        abstract,
        description,
        "<div class='hr'></div>",
-       CfgTable.new(@cls, @cache).to_html,
-       PropertyTable.new(@cls, @cache).to_html,
-       MethodTable.new(@cls, @cache).to_html,
-       EventTable.new(@cls, @cache).to_html,
+       CfgTable.new(@cls, @formatter, @cache).to_html,
+       PropertyTable.new(@cls, @formatter, @cache).to_html,
+       MethodTable.new(@cls, @formatter, @cache).to_html,
+       EventTable.new(@cls, @formatter, @cache).to_html,
        "</div>",
       ].join("\n")
     end
 
     # only render the tree if class has at least one ancestor
     def inheritance_tree
-      @cls.parent ? InheritanceTree.new(@cls).to_html : ""
+      @cls.parent ? InheritanceTree.new(@cls, @formatter).to_html : ""
     end
 
     def heading
@@ -53,13 +62,15 @@ module JsDuck
     def abstract
       [
        "<table cellspacing='0'>",
+        boolean_row("Alternate names:", @cls[:alternateClassNames].join(", ")),
         row("Extends:", extends_link),
         classes_row("Mixins:", @cls.mixins),
-        row("Defind In:", file_link),
+        row("Defined In:", file_link),
         classes_row("Subclasses:", @relations.subclasses(@cls)),
         classes_row("Mixed into:", @relations.mixed_into(@cls)),
         boolean_row("xtype:", @cls[:xtype]),
         boolean_row("Author:", @cls[:author]),
+        boolean_row("Author of docs:", @cls[:docauthor]),
        "</table>",
       ].join("\n")
     end
@@ -92,7 +103,7 @@ module JsDuck
     end
 
     def boolean_row(label, item)
-      item ? row(label, item) : ""
+      (item && item != "") ? row(label, CGI.escapeHTML(item)) : ""
     end
 
     def row(label, info)

data/lib/jsduck/property_table.rb

@@ -3,8 +3,8 @@ require 'jsduck/table'
 module JsDuck
 
   class PropertyTable < Table
-    def initialize(cls, cache={})
-      super(cls, cache)
+    def initialize(cls, formatter, cache={})
+      super(cls, formatter, cache)
       @type = :property
       @id = @cls.full_name + "-props"
       @title = "Public Properties"

data/lib/jsduck/relations.rb

@@ -34,6 +34,10 @@ module JsDuck
       @lookup[classname]
     end
 
+    def each(&block)
+      @classes.each(&block)
+    end
+
     def reg_subclasses(cls)
       if !cls.parent
         # do nothing

data/lib/jsduck/source_file.rb

@@ -0,0 +1,101 @@
+require 'jsduck/js_parser'
+require 'jsduck/css_parser'
+require 'jsduck/merger'
+require "cgi"
+
+module JsDuck
+
+  # Represents one JavaScript or CSS source file.
+  #
+  # The filename parameter determines whether it's parsed as
+  # JavaScript (the default) or CSS.
+  class SourceFile
+    attr_reader :filename
+    attr_reader :contents
+    attr_reader :docs
+    attr_reader :html_filename
+
+    def initialize(contents, filename="")
+      @contents = contents
+      @filename = filename
+      @html_filename = ""
+      @links = {}
+
+      merger = Merger.new
+      @docs = parse.map do |docset|
+        link(docset[:linenr], merger.merge(docset[:comment], docset[:code]))
+      end
+    end
+
+    # loops through each doc-object in file
+    def each(&block)
+      @docs.each(&block)
+    end
+
+    # Sets the html filename of this file,
+    # updating also all doc-objects linking this file
+    def html_filename=(html_filename)
+      @html_filename = html_filename
+      @links.each_value do |line|
+        line.each do |doc|
+          doc[:html_filename] = @html_filename
+          doc[:href] = @html_filename + "#" + id(doc)
+        end
+      end
+    end
+
+    # Returns source code as HTML with lines starting doc-comments specially marked.
+    def to_html
+      linenr = 0
+      return @contents.lines.map do |line|
+        linenr += 1;
+        line = CGI.escapeHTML(line)
+        # wrap the line in as many spans as there are links to this line number.
+        if @links[linenr]
+          @links[linenr].each do |doc|
+            line = "<span id='#{id(doc)}'>#{line}</span>"
+          end
+        end
+        line
+      end.join()
+    end
+
+    def id(doc)
+      if doc[:tagname] == :class
+        doc[:name].gsub(/\./, '-')
+      else
+        # when creation of global class is skipped,
+        # this member property can be nil.
+        (doc[:member] || "global").gsub(/\./, '-') + "-" + doc[:tagname].to_s + "-" + doc[:name]
+      end
+    end
+
+    private
+
+    # Parses the file depending on filename as JS or CSS
+    def parse
+      if @filename =~ /\.s?css$/
+        CssParser.new(@contents).parse
+      else
+        JsParser.new(@contents).parse
+      end
+    end
+
+    # Creates two-way link between sourcefile and doc-object.
+    # If doc-object is class, links also the contained cfgs and constructor.
+    # Returns the modified doc-object after done.
+    def link(linenr, doc)
+      @links[linenr] = [] unless @links[linenr]
+      @links[linenr] << doc
+      doc[:filename] = @filename
+      doc[:linenr] = linenr
+      if doc[:tagname] == :class
+        doc[:cfg].each {|cfg| link(linenr, cfg) }
+        doc[:method].each {|method| link(linenr, method) }
+      end
+      doc
+    end
+
+  end
+
+end

data/lib/jsduck/{source_formatter.rb → source_writer.rb}

@@ -1,28 +1,25 @@
-require "cgi"
-
 module JsDuck
 
-  # Formats JavaScript source into HTML page.  Inside the HTML every
-  # source code line will be marked with ID, so that it can be linked
-  # from documentation.
-  class SourceFormatter
+  # Writes HTML JavaScript/CSS source into HTML file.
+  class SourceWriter
 
     # Initializes SourceFormatter to the directory where
     # HTML-formatted source files will be placed.
     #
-    # formatter can be either :format_page or :format_pre; with the
-    # first one the whole HTML page is created, otherwise just a
-    # contents of <pre> element.
-    def initialize(output_dir, formatter = :format_page)
+    # Wrapper can be either :page or nil; with the first one the whole
+    # HTML page is created, otherwise source is left as is.
+    def initialize(output_dir, wrapper = :page)
       @output_dir = output_dir
-      @formatter = formatter
+      @wrapper = wrapper
     end
 
-    # Converts source to HTML and writes into file in output
-    # directory.  It returns the name of the file that it wrote.
+    # Writes HTML into file in output directory.  It returns the name
+    # of the file that it wrote.
     def write(source, filename)
       fname = uniq_html_filename(filename)
-      File.open(fname, 'w') {|f| f.write(self.send(@formatter, source)) }
+      File.open(fname, 'w') do |f|
+        f.write(@wrapper ? wrap_page(source) : source)
+      end
       fname
     end
 
@@ -40,8 +37,8 @@ module JsDuck
       @output_dir + "/" + File.basename(filename, ".js") + (nr > 0 ? nr.to_s : "") + ".html"
     end
 
-    # Returns full source for HTML page
-    def format_page(source)
+    # Returns source wrapped inside HTML page
+    def wrap_page(source)
       return <<-EOHTML
 <!DOCTYPE html>
 <html>
@@ -60,22 +57,12 @@ module JsDuck
   </script>
 </head>
 <body onload="prettyPrint(); highlight();">
-  <pre class="prettyprint lang-js">#{format_pre(source)}</pre>
+  <pre class="prettyprint lang-js">#{source}</pre>
 </body>
 </html>
       EOHTML
     end
 
-    # Formats the contents of <pre>, wrapping each source code line
-    # inside <span>.
-    def format_pre(source)
-      i = 0
-      return source.lines.collect do |line|
-        i += 1
-        "<span id='line-#{i}'>#{CGI.escapeHTML(line)}</span>"
-      end.join()
-    end
-
   end
 
 end