jsduck 0.6.1 → 2.0.pre

data/lib/jsduck/class.rb

@@ -1,3 +1,5 @@
+require 'jsduck/logger'
+
 module JsDuck
 
   # Encapsulates class documentation and provides some commonly needed
@@ -8,6 +10,8 @@ module JsDuck
 
     def initialize(doc)
       @doc = doc
+      @doc[:members] = Class.default_members_hash if !@doc[:members]
+      @doc[:statics] = Class.default_members_hash if !@doc[:statics]
       @relations = nil
     end
 
@@ -46,8 +50,9 @@ module JsDuck
     def lookup(classname)
       if @relations[classname]
         @relations[classname]
-      elsif classname != "Object"
-        puts "Warning: Class #{classname} not found in #{@doc[:filename]} line #{@doc[:linenr]}"
+      elsif !@relations.ignore?(classname)
+        Logger.instance.warn("Class #{classname} not found in #{@doc[:filename]} line #{@doc[:linenr]}")
+        nil
       end
     end
 
@@ -65,12 +70,11 @@ module JsDuck
     # 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.
+    # For methods the the constructor is listed first.
     #
     # See members_hash for details.
-    def members(type)
-      ms = members_hash(type).values.sort {|a,b| a[:name] <=> b[:name] }
+    def members(type, context=:members)
+      ms = members_hash(type, context).values.sort {|a,b| a[:name] <=> b[:name] }
       type == :method ? constructor_first(ms) : ms
     end
 
@@ -80,11 +84,7 @@ module JsDuck
       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)
+        ms.unshift(constr)
       end
       ms
     end
@@ -95,23 +95,64 @@ module JsDuck
     #
     # 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)
-      all_members = parent ? parent.members_hash(type) : {}
+    def members_hash(type, context=:members)
+      # Singletons have no static members
+      if @doc[:singleton] && context == :statics
+        # Warn if singleton has static members
+        if @doc[context][type].length > 0
+          Logger.instance.warn("Singleton class #{@doc[:name]} can't have static members, remove the @static tag.")
+        end
+        return {}
+      end
+
+      all_members = parent ? parent.members_hash(type, context) : {}
 
       mixins.each do |mix|
-        all_members.merge!(mix.members_hash(type))
+        all_members.merge!(mix.members_hash(type, context))
       end
 
-      @doc[type].each do |m|
+      # For static members, exclude everything not explicitly marked as inheritable
+      if context == :statics
+        all_members.delete_if {|key, member| !member[:inheritable] }
+      end
+
+      (@doc[context][type] || []).each do |m|
         all_members[m[:name]] = m if !m[:private]
       end
 
       all_members
     end
 
+    # Returns member by name.
+    #
+    # Optionally one can also specify type name to differenciate
+    # between different types of members.
+    def get_member(name, type_name=nil)
+      # build hash of all members
+      unless @members_map
+        @members_map = {}
+        [:members, :statics].each do |group|
+          @doc[group].each_key do |type|
+            members_hash(type, group).each_pair do |key, member|
+              @members_map["#{type}-#{key}"] = member
+              @members_map[key] = member
+            end
+          end
+        end
+      end
+
+      @members_map[type_name ? "#{type_name}-#{name}" : name]
+    end
+
+    # Loops through each member of the class, invoking block with each of them
+    def each_member(&block)
+      [:members, :statics].each do |group|
+        @doc[group].each_value do |members|
+          members.each(&block)
+        end
+      end
+    end
+
     # A way to access full class name with similar syntax to
     # package_name and short_name
     def full_name
@@ -155,6 +196,18 @@ module JsDuck
       end
       short
     end
+
+    # Returns default hash that has empty array for each member type
+    def self.default_members_hash
+      return {
+        :cfg => [],
+        :property => [],
+        :method => [],
+        :event => [],
+        :css_var => [],
+        :css_mixin => [],
+      }
+    end
   end
 
 end

data/lib/jsduck/doc_formatter.rb

@@ -2,6 +2,7 @@ require 'rubygems'
 require 'rdiscount'
 require 'strscan'
 require 'cgi'
+require 'jsduck/logger'
 
 module JsDuck
 
@@ -11,8 +12,9 @@ module JsDuck
     # Can contain placeholders:
     #
     # %c - full class name (e.g. "Ext.Panel")
-    # %m - class member name (e.g. "urlEncode")
-    # %M - class member name, prefixed with hash (e.g. "#urlEncode")
+    # %m - class member name prefixed with member type (e.g. "method-urlEncode")
+    # %# - inserts "#" if member name present
+    # %- - inserts "-" if member name present
     # %a - anchor text for link
     #
     # Default value: '<a href="%c%M">%a</a>'
@@ -30,7 +32,11 @@ module JsDuck
     # Sets up instance to work in context of particular class, so
     # that when {@link #blah} is encountered it knows that
     # Context#blah is meant.
-    attr_accessor :context
+    attr_accessor :class_context
+
+    # Sets up instance to work in context of particular doc object.
+    # Used for error reporting.
+    attr_accessor :doc_context
 
     # Maximum length for text that doesn't get shortened, defaults to 120
     attr_accessor :max_length
@@ -43,10 +49,11 @@ module JsDuck
     attr_accessor :relations
 
     def initialize
-      @context = ""
+      @class_context = ""
+      @doc_context = {}
       @max_length = 120
       @relations = {}
-      @link_tpl = '<a href="%c%M">%a</a>'
+      @link_tpl = '<a href="%c%#%m">%a</a>'
       @img_tpl = '<img src="%u" alt="%a"/>'
       @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
       @img_re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
@@ -84,11 +91,13 @@ module JsDuck
       input.sub(@link_re) do
         target = $1
         text = $2
-        if target =~ /^(.*)#(.*)$/
-          cls = $1.empty? ? @context : $1
-          member = $2
+        if target =~ /^(.*)#(?:(.*)-)?(.*)$/
+          cls = $1.empty? ? @class_context : $1
+          type = $2 ? $2.intern : nil
+          member = $3
         else
           cls = target
+          type = false
           member = false
         end
 
@@ -96,12 +105,22 @@ module JsDuck
         if text
           text = text
         elsif member
-          text = (cls == @context) ? member : (cls + "." + member)
+          text = (cls == @class_context) ? member : (cls + "." + member)
         else
           text = cls
         end
 
-        link(cls, member, text)
+        file = @doc_context[:filename]
+        line = @doc_context[:linenr]
+        if !@relations[cls]
+          Logger.instance.warn("#{file} line #{line} #{input} links to non-existing class.")
+          text
+        elsif member && !get_member(cls, member, type)
+          Logger.instance.warn("#{file} line #{line} #{input} links to non-existing member.")
+          text
+        else
+          link(cls, member, text, type)
+        end
       end
     end
 
@@ -114,14 +133,14 @@ module JsDuck
         before = $1
         cls = $2
         hash = $3
-        method = $4
+        member = $4
         after = $5
 
-        if @relations[cls]
-          label = method ? cls+"."+method : cls
-          before + link(cls, method, label) + after
+        if @relations[cls] && (!member || get_member(cls, member))
+          label = member ? cls+"."+member : cls
+          before + link(cls, member, label) + after
         else
-          before + cls + (hash || "") + (method || "") + after
+          before + cls + (hash || "") + (member || "") + after
         end
       end
     end
@@ -141,15 +160,22 @@ module JsDuck
     end
 
     # applies the link template
-    def link(cls, member, anchor_text)
-      @link_tpl.gsub(/(%\w)/) do
+    def link(cls, member, anchor_text, type=nil)
+      # Use the canonical class name for link (not some alternateClassName)
+      cls = @relations[cls].full_name
+      # prepend type name to member name
+      member = member && (get_member(cls, member, type)[:tagname].to_s + "-" + member)
+
+      @link_tpl.gsub(/(%[\w#-])/) do
         case $1
         when '%c'
           cls
         when '%m'
           member ? member : ""
-        when '%M'
-          member ? "#"+member : ""
+        when '%#'
+          member ? "#" : ""
+        when '%-'
+          member ? "-" : ""
         when '%a'
           CGI.escapeHTML(anchor_text||"")
         else
@@ -158,6 +184,10 @@ module JsDuck
       end
     end
 
+    def get_member(cls, member, type=nil)
+      @relations[cls] && @relations[cls].get_member(member, type)
+    end
+
     # Formats doc-comment for placement into HTML.
     # Renders it with Markdown-formatter and replaces @link-s.
     def format(input)
@@ -176,7 +206,7 @@ module JsDuck
       replace(RDiscount.new(input).to_html)
     end
 
-    # Shortens text if needed.
+    # Shortens text
     #
     # 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.
@@ -189,22 +219,27 @@ module JsDuck
     #
     #   Blah blah blah some text.
     #
-    # Ellipsis is only added when input actually gets shortened.
     def shorten(input)
-      if too_long?(input)
-        strip_tags(input)[0..(@max_length-4)] + "..."
+      sent = first_sentence(strip_tags(input))
+      if sent.length > @max_length
+        sent[0..(@max_length-4)] + "..."
       else
-        input
+        sent + " ..."
       end
     end
 
+    def first_sentence(str)
+      str.sub(/\A(.+?\.)\s.*\Z/m, "\\1")
+    end
+
     # Returns true when input should get shortened.
     def too_long?(input)
-      strip_tags(input).length > @max_length
+      stripped = strip_tags(input)
+      first_sentence(stripped).length < stripped.length || stripped.length > @max_length
     end
 
     def strip_tags(str)
-      str.gsub(/<.*?>/, "")
+      str.gsub(/<.*?>/, "").strip
     end
   end
 

data/lib/jsduck/doc_parser.rb

@@ -97,21 +97,34 @@ module JsDuck
           at_type
         elsif look(/@xtype\b/)
           at_xtype
+        elsif look(/@ftype\b/)
+          at_ftype
         elsif look(/@member\b/)
           at_member
+        elsif look(/@alias\b/)
+          at_alias
         elsif look(/@author\b/)
           at_author
         elsif look(/@docauthor\b/)
           at_docauthor
+        elsif look(/@deprecated\b/)
+          at_deprecated
         elsif look(/@var\b/)
           at_var
         elsif look(/@static\b/)
           boolean_at_tag(/@static/, :static)
-        elsif look(/@(private|ignore|hide|protected)\b/)
-          boolean_at_tag(/@(private|ignore|hide|protected)/, :private)
+        elsif look(/@inheritable\b/)
+          boolean_at_tag(/@inheritable/, :inheritable)
+        elsif look(/@(private|ignore|hide)\b/)
+          boolean_at_tag(/@(private|ignore|hide)/, :private)
+        elsif look(/@protected\b/)
+          boolean_at_tag(/@protected/, :protected)
         elsif look(/@markdown\b/)
           # this is detected just to be ignored
           boolean_at_tag(/@markdown/, :markdown)
+        elsif look(/@abstract\b/)
+          # this is detected just to be ignored
+          boolean_at_tag(/@abstract/, :abstract)
         elsif look(/@/)
           @current_tag[:doc] += @input.scan(/@/)
         elsif look(/[^@]/)
@@ -244,6 +257,14 @@ module JsDuck
       skip_white
     end
 
+    # matches @ftype name
+    def at_ftype
+      match(/@ftype/)
+      add_tag(:ftype)
+      maybe_ident_chain(:name)
+      skip_white
+    end
+
     # matches @member name ...
     def at_member
       match(/@member/)
@@ -252,6 +273,25 @@ module JsDuck
       skip_white
     end
 
+    # matches @alias class.name#type-member
+    def at_alias
+      match(/@alias/)
+      add_tag(:alias)
+      skip_horiz_white
+      if look(/\w/)
+        @current_tag[:cls] = ident_chain
+        if look(/#\w/)
+          @input.scan(/#/)
+          if look(/\w+-\w+/)
+            @current_tag[:type] = ident
+            @input.scan(/-/)
+          end
+          @current_tag[:member] = ident
+        end
+      end
+      skip_white
+    end
+
     # matches @author some name ... newline
     def at_author
       match(/@author/)
@@ -270,6 +310,17 @@ module JsDuck
       skip_white
     end
 
+    # matches @deprecated <version> some text ... newline
+    def at_deprecated
+      match(/@deprecated/)
+      add_tag(:deprecated)
+      skip_horiz_white
+      @current_tag[:version] = @input.scan(/[0-9.]+/)
+      skip_horiz_white
+      @current_tag[:text] = @input.scan(/.*$/)
+      skip_white
+    end
+
     # Used to match @private, @ignore, @hide, ...
     def boolean_at_tag(regex, propname)
       match(regex)

data/lib/jsduck/exporter.rb

@@ -17,18 +17,11 @@ module JsDuck
     # Returns all data in Class object as hash.
     def export(cls)
       h = cls.to_hash
-      h[:cfgs] = cls.members(:cfg)
-      h.delete(:cfg)
-      h[:properties] = cls.members(:property)
-      h.delete(:property)
-      h[:methods] = cls.members(:method)
-      h.delete(:method)
-      h[:events] = cls.members(:event)
-      h.delete(:event)
-      h[:cssVars] = cls.members(:css_var)
-      h.delete(:css_var)
-      h[:cssMixins] = cls.members(:css_mixin)
-      h.delete(:css_mixin)
+      h[:members] = {}
+      Class.default_members_hash.each_key do |key|
+        h[:members][key] = cls.members(key)
+        h[:statics][key] = cls.members(key, :statics)
+      end
       h[:component] = cls.inherits_from?("Ext.Component")
       h[:superclasses] = cls.superclasses.collect {|c| c.full_name }
       h[:subclasses] = @relations.subclasses(cls).collect {|c| c.full_name }
@@ -39,17 +32,23 @@ module JsDuck
 
     # converts :doc properties from markdown to html and resolve @links
     def format_class(c)
-      @formatter.context = c[:name]
+      @formatter.class_context = c[:name]
+      @formatter.doc_context = c
       c[:doc] = @formatter.format(c[:doc]) if c[:doc]
-      [:cfgs, :properties, :methods, :events, :cssVars, :cssMixins].each do |type|
-        c[type] = c[type].map {|m| format_member(m) }
+      c[:members].each_pair do |type, members|
+        c[:members][type] = members.map {|m| format_member(m) }
+      end
+      c[:statics].each_pair do |type, members|
+        c[:statics][type] = members.map {|m| format_member(m) }
       end
       c
     end
 
     def format_member(m)
       m = m.clone
+      @formatter.doc_context = m
       m[:doc] = @formatter.format(m[:doc]) if m[:doc]
+      m[:deprecated][:text] = @formatter.format(m[:deprecated][:text]) if m[:deprecated]
       if m[:params] || @formatter.too_long?(m[:doc])
         m[:shortDoc] = @formatter.shorten(m[:doc])
       end