jsduck 0.1

data/lib/jsduck/cfg_table.rb

@@ -0,0 +1,21 @@
+require 'jsduck/table'
+
+module JsDuck
+
+  class CfgTable < Table
+    def initialize(cls)
+      super(cls)
+      @type = :cfg
+      @id = @cls.full_name + "-configs"
+      @title = "Config Options"
+      @column_title = "Config Options"
+      @row_class = "config-row"
+    end
+
+    def signature_suffix(item)
+      " : " + item[:type]
+    end
+
+  end
+
+end

data/lib/jsduck/class.rb

@@ -0,0 +1,116 @@
+module JsDuck
+
+  # Encapsulates class documentation and provides some commonly needed
+  # methods on it.  Otherwise it acts like Hash, providing the []
+  # method.
+  class Class
+    def initialize(doc, classes={})
+      @doc = doc
+      @classes = classes
+    end
+
+    def [](key)
+      @doc[key]
+    end
+
+    # Returns instance of parent class, or nil if there is none
+    def parent
+      @doc[:extends] ? @classes[@doc[:extends]] : nil
+    end
+
+    # Returns true when this class inherits from the specified class.
+    # Also returns true when the class itself is the one we are asking about.
+    def inherits_from?(class_name)
+      return full_name == class_name || (parent ? parent.inherits_from?(class_name) : false)
+    end
+
+    # Returns array of all public members of particular type in a class,
+    # sorted by name.
+    #
+    # For methods the the constructor is listed as first method having
+    # the same name as class itself.
+    #
+    # See members_hash for details.
+    def members(type)
+      ms = members_hash(type).values.sort {|a,b| a[:name] <=> b[:name] }
+      type == :method ? constructor_first(ms) : ms
+    end
+
+    # If methods list contains constructor, rename it with class name
+    # and move into beginning of methods list.
+    def constructor_first(ms)
+      constr = ms.find {|m| m[:name] == "constructor" }
+      if constr
+        ms.delete(constr)
+        # Clone it.  Otherwise the search for "constructor" from this
+        # class will return nothing as we have renamed it.
+        constr2 = constr.clone
+        constr2[:name] = short_name
+        ms.unshift(constr2)
+      end
+      ms
+    end
+
+    # Returns hash of public members of class (and parent classes).
+    # Members are methods, properties, cfgs, events (member type
+    # is speified through 'type' parameter).
+    #
+    # When parent and child have members with same name,
+    # member from child overrides tha parent member.
+    #
+    # We also set :member property to each member to the full class
+    # name where it belongs, so one can tell them apart afterwards.
+    def members_hash(type)
+      parent_members = parent ? parent.members_hash(type) : {}
+      @doc[type].each do |m|
+        parent_members[m[:name]] = m if !m[:private]
+      end
+      parent_members
+    end
+
+    # A way to access full class name with similar syntax to
+    # package_name and short_name
+    def full_name
+      @doc[:name]
+    end
+
+    # Returns package name of the class.
+    #
+    # That is the namespace part of full class name.
+    #
+    # For example "My.package" is package_name of "My.package.Class"
+    def package_name
+      Class.package_name(@doc[:name])
+    end
+
+    # Returns last part of full class name
+    #
+    # For example for "My.package.Class" it is "Class"
+    def short_name
+      Class.short_name(@doc[:name])
+    end
+
+    # Static methods
+
+    # Utility method that given a package or class name finds the name
+    # of its parent package.
+    def self.package_name(name)
+      name.slice(0, name.length - self.short_name(name).length - 1) || ""
+    end
+
+    # Utility method that given full package or class name extracts
+    # the "class"-part of the name.
+    #
+    # Because we try to emulate ext-doc, it's not as simple as just
+    # taking the last part.  See class_spec.rb for details.
+    def self.short_name(name)
+      parts = name.split(/\./)
+      short = parts.pop
+      while parts.length > 1 && parts.last =~ /^[A-Z]/
+        short = parts.pop + "." + short
+      end
+      short
+    end
+  end
+
+end

data/lib/jsduck/doc_formatter.rb

@@ -0,0 +1,69 @@
+require 'rubygems'
+require 'rdiscount'
+
+module JsDuck
+
+  # Formats doc-comments
+  class DocFormatter
+    # Initializes instance to work in context of particular class, so
+    # that when {@link #blah} is encountered it knows that
+    # Context#blah is meant.
+    def initialize(context)
+      @context = context
+    end
+
+    # Replaces {@link Class#member link text} in given string with
+    # HTML links pointing to documentation.  In addition to the href
+    # attribute links will also contain ext:cls and ext:member
+    # attributes.
+    def replace(input)
+      input.gsub(/\{@link +(\S*?)(?: +(.+?))?\}/) do
+        target = $1
+        text = $2
+        if target =~ /^(.*)#(.*)$/
+          cls = $1.empty? ? @context : $1
+          member = $2
+        else
+          cls = target
+          member = false
+        end
+
+        # Construct link attributes
+        href = " href=\"output/#{cls}.html" + (member ? "#" + cls + "-" + member : "") + '"'
+        ext_cls = ' ext:cls="' + cls + '"'
+        ext_member = member ? ' ext:member="' + member + '"' : ""
+
+        # Construct link text
+        if text
+          text = text
+        elsif member
+          text = (cls == @context) ? member : (cls + "." + member)
+        else
+          text = cls
+        end
+
+        "<a" + href + ext_cls + ext_member + ">" + text + "</a>"
+      end
+    end
+
+    # Formats doc-comment for placement into HTML.
+    # Renders it with Markdown-formatter and replaces @link-s.
+    def format(input)
+      # In ExtJS source "<pre>" is often at the end of paragraph, not
+      # on its own line.  But in that case RDiscount doesn't recognize
+      # it as the beginning of <pre>-block and goes on parsing it as
+      # normal Markdown, which often causes nested <pre>-blocks.
+      #
+      # To prevent this, we always add extra newline before <pre>.
+      input.gsub!(/([^\n])<pre>/, "\\1\n<pre>")
+
+      # But we remove trailing newline after <pre> to prevent
+      # code-blocks beginning with empty line.
+      input.gsub!(/<pre>(<code>)?\n?/, "<pre>\\1")
+
+      replace(RDiscount.new(input).to_html)
+    end
+
+  end
+
+end

data/lib/jsduck/doc_parser.rb

@@ -0,0 +1,277 @@
+require 'strscan'
+
+module JsDuck
+
+  # Parses doc-comment into array of @tags
+  #
+  # For each @tag it produces Hash like the following:
+  #
+  #     {
+  #       :tagname => :cfg/:property/:type/:extends/...,
+  #       :doc => "Some documentation for this tag",
+  #       ...@tag specific stuff like :name, :type, and so on...
+  #     }
+  #
+  # When doc-comment begins with comment, not preceded by @tag, then
+  # the comment will be placed into Hash with :tagname => :default.
+  #
+  # Unrecognized @tags are left as is into documentation as if they
+  # were normal text.
+  #
+  # @see and {@link} are parsed separately in JsDuck::DocFormatter.
+  #
+  class DocParser
+    def parse(input)
+      @tags = []
+      @input = StringScanner.new(purify(input))
+      parse_loop
+      # The parsing process can leave whitespace at the ends of
+      # doc-strings, here we get rid of it.  Additionally null all empty docs
+      @tags.each do |tag|
+        tag[:doc].strip!
+        tag[:doc] = nil if tag[:doc] == ""
+      end
+      # Get rid of empty default tag
+      if @tags.first && @tags.first[:tagname] == :default && !@tags.first[:doc]
+        @tags.shift
+      end
+      @tags
+    end
+
+    # Extracts content inside /** ... */
+    def purify(input)
+      result = []
+      # Remove the beginning /** and end */
+      input = input.sub(/\A\/\*\* ?/, "").sub(/ ?\*\/\Z/, "")
+      # Now we are left with only two types of lines:
+      # - those beginning with *
+      # - and those without it
+      input.each_line do |line|
+        line.chomp!
+        if line =~ /\A\s*\*\s?(.*)\Z/ then
+          result << $1
+        else
+          result << line
+        end
+      end
+      return result.join("\n")
+    end
+
+    def add_tag(tag)
+      @tags << @current_tag = {:tagname => tag, :doc => ""}
+    end
+
+    def parse_loop
+      add_tag(:default)
+      while !@input.eos? do
+        if look(/@class\b/) then
+          at_class
+        elsif look(/@extends\b/) then
+          at_extends
+        elsif look(/@singleton\b/) then
+          boolean_at_tag(/@singleton/, :singleton)
+        elsif look(/@event\b/) then
+          at_event
+        elsif look(/@method\b/) then
+          at_method
+        elsif look(/@constructor\b/) then
+          boolean_at_tag(/@constructor/, :constructor)
+        elsif look(/@param\b/) then
+          at_param
+        elsif look(/@returns?\b/) then
+          at_return
+        elsif look(/@cfg\b/) then
+          at_cfg
+        elsif look(/@property\b/) then
+          at_property
+        elsif look(/@type\b/) then
+          at_type
+        elsif look(/@xtype\b/) then
+          at_xtype
+        elsif look(/@member\b/) then
+          at_member
+        elsif look(/@static\b/) then
+          boolean_at_tag(/@static/, :static)
+        elsif look(/@(private|ignore|hide|protected)\b/) then
+          boolean_at_tag(/@(private|ignore|hide|protected)/, :private)
+        elsif look(/@/) then
+          @current_tag[:doc] += @input.scan(/@/)
+        elsif look(/[^@]/) then
+          @current_tag[:doc] += @input.scan(/[^@]+/)
+        end
+      end
+    end
+
+    # matches @class name ...
+    def at_class
+      match(/@class/)
+      add_tag(:class)
+      maybe_ident_chain(:name)
+      skip_white
+    end
+
+    # matches @extends name ...
+    def at_extends
+      match(/@extends/)
+      add_tag(:extends)
+      maybe_ident_chain(:extends)
+      skip_white
+    end
+
+    # matches @event name ...
+    def at_event
+      match(/@event/)
+      add_tag(:event)
+      maybe_name
+      skip_white
+    end
+
+    # matches @method name ...
+    def at_method
+      match(/@method/)
+      add_tag(:method)
+      maybe_name
+      skip_white
+    end
+
+    # matches @param {type} variable ...
+    def at_param
+      match(/@param/)
+      add_tag(:param)
+      maybe_type
+      maybe_name
+      skip_white
+    end
+
+    # matches @return {type} ...
+    def at_return
+      match(/@returns?/)
+      add_tag(:return)
+      maybe_type
+      skip_white
+    end
+
+    # matches @cfg {type} name ...
+    def at_cfg
+      match(/@cfg/)
+      add_tag(:cfg)
+      maybe_type
+      maybe_name
+      skip_white
+    end
+
+    # matches @property {type} name ...
+    #
+    # ext-doc doesn't support {type} and name for @property - name is
+    # inferred from source and @type is required to specify type,
+    # jsdoc-toolkit on the other hand follows the sensible route, and
+    # so do we.
+    def at_property
+      match(/@property/)
+      add_tag(:property)
+      maybe_type
+      maybe_name
+      skip_white
+    end
+
+    # matches @type {type}  or  @type type
+    #
+    # The presence of @type implies that we are dealing with property.
+    # ext-doc allows type name to be either inside curly braces or
+    # without them at all.
+    def at_type
+      match(/@type/)
+      add_tag(:type)
+      skip_horiz_white
+      if look(/\{/) then
+        @current_tag[:type] = typedef
+      elsif look(/\S/) then
+        @current_tag[:type] = @input.scan(/\S+/)
+      end
+      skip_white
+    end
+
+    # matches @xtype name
+    def at_xtype
+      match(/@xtype/)
+      add_tag(:xtype)
+      maybe_name
+      skip_white
+    end
+
+    # matches @member name ...
+    def at_member
+      match(/@member/)
+      add_tag(:member)
+      maybe_ident_chain(:member)
+      skip_white
+    end
+
+    # Used to match @private, @ignore, @hide, ...
+    def boolean_at_tag(regex, propname)
+      match(regex)
+      add_tag(propname)
+      skip_white
+    end
+
+    # matches {type} if possible and sets it on @current_tag
+    def maybe_type
+      skip_horiz_white
+      if look(/\{/) then
+        @current_tag[:type] = typedef
+      end
+    end
+
+    # matches identifier name if possible and sets it on @current_tag
+    def maybe_name
+      skip_horiz_white
+      if look(/\w/) then
+        @current_tag[:name] = ident
+      end
+    end
+
+    # matches ident.chain if possible and sets it on @current_tag
+    def maybe_ident_chain(propname)
+      skip_horiz_white
+      if look(/\w/) then
+        @current_tag[propname] = ident_chain
+      end
+    end
+
+    # matches {...} and returns text inside brackets
+    def typedef
+      match(/\{/)
+      name = @input.scan(/[^}]+/)
+      match(/\}/)
+      return name
+    end
+
+    # matches chained.identifier.name and returns it
+    def ident_chain
+      @input.scan(/[\w.]+/)
+    end
+
+    # matches identifier and returns its name
+    def ident
+      @input.scan(/\w+/)
+    end
+
+    def look(re)
+      @input.check(re)
+    end
+
+    def match(re)
+      @input.scan(re)
+    end
+
+    def skip_white
+      @input.scan(/\s+/)
+    end
+
+    # skips horizontal whitespace (tabs and spaces)
+    def skip_horiz_white
+      @input.scan(/[ \t]+/)
+    end
+  end
+
+end