jsduck 5.0.0.beta01 → 5.0.0.beta2

data/lib/jsduck/process/lint.rb

@@ -40,14 +40,26 @@ module JsDuck
       # print warning for each class or public member with no name
       def warn_no_doc
         @relations.each do |cls|
-          if cls[:doc] == ""
+
+          if cls[:doc] == "" && !cls[:private]
             warn(:no_doc, "No documentation for #{cls[:name]}", cls)
           end
-        end
-        each_member do |member|
-          if member[:doc] == "" && !member[:private] && !member[:hide] && !JsDuck::Class.constructor?(member)
-            warn(:no_doc, "No documentation for #{member[:owner]}##{member[:name]}", member)
+
+          cls.all_local_members.each do |member|
+            if !member[:private] && !member[:hide] && !JsDuck::Class.constructor?(member)
+              if member[:doc] == ""
+                warn(:no_doc, "No documentation for #{member[:owner]}##{member[:name]}", member)
+              end
+
+              (member[:params] || []).each do |p|
+                if p[:doc] == ""
+                  warn(:no_doc, "No documentation for parameter #{p[:name]} of #{member[:owner]}##{member[:name]}", member)
+                end
+              end
+
+            end
           end
+
         end
       end
 
@@ -125,8 +137,7 @@ module JsDuck
 
       # Prints warning + filename and linenumber from doc-context
       def warn(type, msg, member)
-        context = member[:files][0]
-        Logger.warn(type, msg, context[:filename], context[:linenr])
+        Logger.warn(type, msg, member[:files][0])
       end
 
     end

data/lib/jsduck/process/overrides.rb

@@ -37,8 +37,7 @@ module JsDuck
       def process(override)
         target = @classes_hash[override[:override]]
         unless target
-          ctx = override[:files][0]
-          return Logger.warn(:extend, "Class #{override[:override]} not found", ctx[:filename], ctx[:linenr])
+          return Logger.warn(:extend, "Class #{override[:override]} not found", override[:files][0])
         end
 
         # Combine comments of classes

data/lib/jsduck/render/class.rb

@@ -45,7 +45,7 @@ module JsDuck
       end
 
       def render_section(sec)
-        members = @cls[:members][sec[:name]] + @cls[:statics][sec[:name]]
+        members = @cls[:members].find_all {|m| m[:tagname] == sec[:name] }
 
         # Skip rendering empty sections
         return [] if members.length == 0

data/lib/jsduck/tag/alias.rb

@@ -6,6 +6,7 @@ module JsDuck::Tag
     def initialize
       @pattern = "alias"
       @tagname = :aliases
+      @repeatable = true
       @ext_define_pattern = "alias"
       @ext_define_default = {:aliases => []}
       @merge_context = :class
@@ -14,7 +15,7 @@ module JsDuck::Tag
     # For backwards compatibility decide whether the @alias was used
     # as @inheritdoc (@alias used to have the meaning of @inheritdoc
     # before) or as a real Ext4 style alias definition.
-    def parse_doc(p)
+    def parse_doc(p, pos)
       if p.look(/([\w.]+)?#\w+/)
         parse_as_inheritdoc(p)
       else

data/lib/jsduck/tag/alternate_class_names.rb

@@ -5,6 +5,7 @@ module JsDuck::Tag
     def initialize
       @pattern = ["alternateClassName", "alternateClassNames"]
       @tagname = :alternateClassNames
+      @repeatable = true
       @ext_define_pattern = "alternateClassName"
       @ext_define_default = {:alternateClassNames => []}
       @merge_context = :class

data/lib/jsduck/tag/aside.rb

@@ -6,11 +6,12 @@ module JsDuck::Tag
     def initialize
       @pattern = "aside"
       @tagname = :aside
+      @repeatable = true
       @html_position = POS_ASIDE
     end
 
     # Parses: @aside [ guide | video| example ] name
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :aside,
         :type => aside_type(p),
@@ -62,8 +63,7 @@ module JsDuck::Tag
     end
 
     def warn(msg, context)
-      file = context[:files][0]
-      JsDuck::Logger.warn(:aside, msg, file[:filename], file[:linenr])
+      JsDuck::Logger.warn(:aside, msg, context[:files][0])
       nil
     end
 

data/lib/jsduck/tag/author.rb

@@ -1,15 +1,30 @@
 require "jsduck/tag/tag"
 
 module JsDuck::Tag
+  # Author tag gets processed, but no output gets created.  Users of
+  # JSDuck may override this tag to make it print the names of
+  # authors.
   class Author < Tag
     def initialize
       @pattern = "author"
+      @tagname = :author
+      @repeatable = true
     end
 
     # @author Name of Author <email@example.com> ...
-    # Everything until the end of line gets just ignored.
-    def parse_doc(p)
-      p.match(/.*$/)
+    def parse_doc(p, pos)
+      name = p.match(/[^<\n]*/).strip
+      if p.look(/</)
+        p.match(/</)
+        email = p.match(/[^>\n]*/)
+        p.match(/>/)
+      end
+
+      return {:tagname => @tagname, :name => name, :email => email}
+    end
+
+    def process_doc(context, tags, pos)
+      context[@tagname] = tags
     end
   end
 end

data/lib/jsduck/tag/autodetected.rb

@@ -0,0 +1,21 @@
+require "jsduck/tag/tag"
+require "jsduck/docs_code_comparer"
+
+module JsDuck::Tag
+  # There is no @autodetected tag.
+  #
+  # This tag class exists to take care of the merging of :autodetected
+  # field.
+  class Autodetected < Tag
+    def initialize
+      @tagname = :autodetected
+      @merge_context = [:class, :member]
+    end
+
+    def merge(h, docs, code)
+      if docs[:autodetected] || code[:autodetected]
+        h[:autodetected] = (code[:autodetected] || {}).merge(docs[:autodetected] || {})
+      end
+    end
+  end
+end

data/lib/jsduck/tag/boolean_tag.rb

@@ -12,7 +12,7 @@ module JsDuck::Tag
     end
 
     # Parses just the name of the tag.
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {:tagname => @tagname}
     end
 

data/lib/jsduck/tag/cfg.rb

@@ -6,6 +6,7 @@ module JsDuck::Tag
     def initialize
       @pattern = "cfg"
       @tagname = :cfg
+      @repeatable = true
       @member_type = {
         :name => :cfg,
         :category => :property_like,
@@ -20,7 +21,7 @@ module JsDuck::Tag
     end
 
     # @cfg {Type} [name=default] (required) ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       tag = p.standard_tag({:tagname => :cfg, :type => true, :name => true})
       tag[:optional] = false if parse_required(p)
       tag[:doc] = :multiline
@@ -33,13 +34,16 @@ module JsDuck::Tag
 
     def process_doc(h, tags, pos)
       p = tags[0]
-      h[:name] = p[:name]
       h[:type] = p[:type]
       h[:default] = p[:default]
-      h[:properties] = JsDuck::Doc::Subproperties.nest(tags, pos)[0][:properties]
       h[:required] = true if p[:optional] == false
+
       # Documentation after the first @cfg is part of the top-level docs.
       h[:doc] += p[:doc]
+
+      nested = JsDuck::Doc::Subproperties.nest(tags, pos)[0]
+      h[:properties] = nested[:properties]
+      h[:name] = nested[:name]
     end
   end
 end

data/lib/jsduck/tag/class.rb

@@ -9,7 +9,7 @@ module JsDuck::Tag
     end
 
     # @class name
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :class,
         :name => p.ident_chain,

data/lib/jsduck/tag/class_list_tag.rb

@@ -13,7 +13,7 @@ module JsDuck::Tag
   # #parse_ext_define to work.
   #
   class ClassListTag < Tag
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => @tagname,
         :classes => classname_list(p),

data/lib/jsduck/tag/constructor.rb

@@ -8,7 +8,7 @@ module JsDuck::Tag
     end
 
     # @constructor
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {:tagname => :constructor, :doc => :multiline}
     end
 

data/lib/jsduck/tag/css_var.rb

@@ -15,7 +15,7 @@ module JsDuck::Tag
     end
 
     # @var {Type} [name=default] ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       p.standard_tag({:tagname => :css_var, :type => true, :name => true})
     end
 

data/lib/jsduck/tag/default.rb

@@ -19,7 +19,7 @@ module JsDuck::Tag
     end
 
     def merge(h, docs, code)
-      h[:default] = JsDuck::DocsCodeComparer.merge_if_matches(:default, docs, code)
+      JsDuck::DocsCodeComparer.merge_if_matches(h, :default, docs, code)
     end
 
     def to_html(m)

data/lib/jsduck/tag/deprecated_tag.rb

@@ -25,7 +25,7 @@ module JsDuck::Tag
       end
     end
 
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => @tagname,
         :version => p.match(/[0-9.]+/),

data/lib/jsduck/tag/docauthor.rb

@@ -4,7 +4,9 @@ module JsDuck::Tag
   # Exactly the same as @author tag - it's simply ignored.
   class Docauthor < Author
     def initialize
+      super
       @pattern = "docauthor"
+      @tagname = :docauthor
     end
   end
 end

data/lib/jsduck/tag/enum.rb

@@ -18,7 +18,7 @@ module JsDuck::Tag
     end
 
     # @enum {Type} [name=default] ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       enum = p.standard_tag({:tagname => :enum, :type => true, :name => true})
 
       # @enum is a special case of class, so we also generate a class
@@ -46,7 +46,7 @@ module JsDuck::Tag
 
     def to_html(cls)
       if cls[:enum][:doc_only]
-        first = cls[:members][:property][0] || {:name => 'foo', :default => '"foo"'}
+        first = cls[:members][0] || {:name => 'foo', :default => '"foo"'}
         [
           "<div class='rounded-box enum-box'>",
           "<p><strong>ENUM:</strong> ",

data/lib/jsduck/tag/event.rb

@@ -14,7 +14,7 @@ module JsDuck::Tag
     end
 
     # @event name ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :event,
         :name => p.ident,

data/lib/jsduck/tag/extends.rb

@@ -14,7 +14,7 @@ module JsDuck::Tag
     # @extends classname
     # or
     # @extends {classname}
-    def parse_doc(p)
+    def parse_doc(p, pos)
       if p.match(/\{/)
         cls = p.ident_chain
         p.match(/\}/)

data/lib/jsduck/tag/ftype.rb

@@ -4,10 +4,11 @@ module JsDuck::Tag
   class Ftype < Xtype
     def initialize
       @pattern = "ftype"
+      @repeatable = true
     end
 
     # @ftype name
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :aliases,
         :name => parse_alias_shorthand(p, "feature")

data/lib/jsduck/tag/inheritdoc.rb

@@ -9,7 +9,7 @@ module JsDuck::Tag
     end
 
     # @inheritdoc class.name#static-type-member
-    def parse_doc(p)
+    def parse_doc(p, pos)
       parse_as_inheritdoc(p)
     end
 

data/lib/jsduck/tag/localdoc.rb

@@ -0,0 +1,33 @@
+require "jsduck/tag/tag"
+require 'jsduck/format/shortener'
+
+module JsDuck::Tag
+  # Non-inheritable documentation
+  class Localdoc < Tag
+    def initialize
+      @pattern = "localdoc"
+      @tagname = :localdoc
+      @html_position = POS_LOCALDOC
+    end
+
+    def parse_doc(p, pos)
+      {
+        :tagname => :localdoc,
+        :doc => :multiline,
+      }
+    end
+
+    def process_doc(m, tags, pos)
+      m[:localdoc] = tags.map {|t| t[:doc] }.join("\n\n")
+    end
+
+    def format(m, formatter)
+      m[:localdoc] = formatter.format(m[:localdoc])
+    end
+
+    def to_html(m)
+      m[:localdoc]
+    end
+
+  end
+end

data/lib/jsduck/tag/markdown.rb

@@ -7,7 +7,7 @@ module JsDuck::Tag
     end
 
     # @markdown
-    def parse_doc(p)
+    def parse_doc(p, pos)
       # Just completely ignore this tag.
     end
   end

data/lib/jsduck/tag/member.rb

@@ -10,7 +10,7 @@ module JsDuck::Tag
     end
 
     # @member classname
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :owner,
         :owner => p.ident_chain,

data/lib/jsduck/tag/method.rb

@@ -19,7 +19,7 @@ module JsDuck::Tag
     end
 
     # @method name ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :method,
         :name => p.ident,

data/lib/jsduck/tag/mixins.rb

@@ -5,6 +5,7 @@ module JsDuck::Tag
     def initialize
       @pattern = ["mixin", "mixins"]
       @tagname = :mixins
+      @repeatable = true
       @ext_define_pattern = "mixins"
       @ext_define_default = {:mixins => []}
     end

data/lib/jsduck/tag/override.rb

@@ -10,7 +10,7 @@ module JsDuck::Tag
     end
 
     # @override nameOfOverride
-    def parse_doc(p)
+    def parse_doc(p, pos)
       if classname = p.ident_chain
         {
           :tagname => :override,

data/lib/jsduck/tag/param.rb

@@ -9,12 +9,13 @@ module JsDuck::Tag
     def initialize
       @pattern = "param"
       @tagname = :params
+      @repeatable = true
       @merge_context = :method_like
       @html_position = POS_PARAM
     end
 
     # @param {Type} [name=default] (optional) ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       tag = p.standard_tag({:tagname => :params, :type => true, :name => true})
       tag[:optional] = true if parse_optional(p)
       tag[:doc] = :multiline
@@ -31,6 +32,10 @@ module JsDuck::Tag
 
     def merge(h, docs, code)
       h[:params] = merge_params(docs, code, h[:files].first)
+
+      if only_autodetected_params?(docs, code)
+        JsDuck::DocsCodeComparer.mark_autodetected(h, :params)
+      end
     end
 
     def format(m, formatter)
@@ -43,6 +48,10 @@ module JsDuck::Tag
 
     private
 
+    def only_autodetected_params?(docs, code)
+      (docs[:params] || []).length == 0 && (code[:params] || []).length > 0
+    end
+
     def merge_params(docs, code, file)
       explicit = docs[:params] || []
       implicit = JsDuck::DocsCodeComparer.matches?(docs, code) ? (code[:params] || []) : []
@@ -50,19 +59,21 @@ module JsDuck::Tag
       im_len = implicit.length
 
       if ex_len == 0 || im_len == 0
-        # Skip
+        # Skip when either no implicit or explicit params
+      elsif ex_len != im_len && explicit.last[:type] =~ /\.\.\.$/
+        # Skip when vararg params are in play.
       elsif ex_len < im_len
         # Warn when less parameters documented than found from code.
-        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but only #{ex_len} documented.", file[:filename], file[:linenr])
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but only #{ex_len} documented.", file)
       elsif ex_len > im_len
         # Warn when more parameters documented than found from code.
-        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but #{ex_len} documented.", file[:filename], file[:linenr])
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but #{ex_len} documented.", file)
       elsif implicit.map {|p| p[:name] } != explicit.map {|p| p[:name] }
         # Warn when parameter names don't match up.
         ex_names = explicit.map {|p| p[:name] }
         im_names = implicit.map {|p| p[:name] }
         str = ex_names.zip(im_names).map {|p| ex, im = p; ex == im ? ex : (ex||"")+"/"+(im||"") }.join(", ")
-        JsDuck::Logger.warn(:param_count, "Documented and auto-detected params don't match: #{str}", file[:filename], file[:linenr])
+        JsDuck::Logger.warn(:param_count, "Documented and auto-detected params don't match: #{str}", file)
       end
 
       # Override implicit parameters with explicit ones