jsduck 3.1.0 → 3.2.1

data/lib/jsduck/index_html.rb

@@ -34,9 +34,6 @@ module JsDuck
         "{header}" => @opts.header,
         "{footer}" => "<div id='footer-content' style='display: none'>#{@opts.footer}</div>",
         "{extjs_path}" => @opts.extjs_path,
-        "{local_storage_db}" => @opts.local_storage_db,
-        "{show_print_button}" => @opts.seo ? "true" : "false",
-        "{touch_examples_ui}" => @opts.touch_examples_ui ? "true" : "false",
         "{welcome}" => @welcome.to_html,
         "{categories}" => @categories.to_html,
         "{guides}" => @guides.to_html,

data/lib/jsduck/inherit_doc.rb

@@ -1,4 +1,5 @@
 require 'jsduck/logger'
+require 'pp'
 
 module JsDuck
 
@@ -41,19 +42,34 @@ module JsDuck
           warn("@inheritdoc #{inherit[:cls]}##{inherit[:member]} - class not found", context)
           return m
         end
-        parent = parent_cls.get_member(inherit[:member], inherit[:type] || m[:tagname])
+        parent = parent_cls.get_members(inherit[:member], inherit[:type] || m[:tagname], inherit[:static] || m[:meta][:static])[0]
         unless parent
           warn("@inheritdoc #{inherit[:cls]}##{inherit[:member]} - member not found", context)
           return m
         end
       else
         parent_cls = @relations[m[:owner]].parent
-        unless parent_cls
+        mixins = @relations[m[:owner]].mixins
+        # Warn when no parent or mixins at all
+        if !parent_cls && mixins.length == 0
           warn("@inheritdoc - parent class not found", context)
           return m
         end
-        parent = parent_cls.get_member(m[:name], m[:tagname])
-        unless parent
+        # First check for the member in all mixins, because members
+        # from mixins override those from parent class.  Looking first
+        # from mixins is probably a bit slower, but it's the correct
+        # order to do things.
+        if mixins.length > 0
+          parent = mixins.map do |mix|
+            mix.get_members(m[:name], m[:tagname], m[:meta][:static])[0]
+          end.compact.first
+        end
+        # When not found, try looking from parent class
+        if !parent && parent_cls
+          parent = parent_cls.get_members(m[:name], m[:tagname], m[:meta][:static])[0]
+        end
+        # Only when both parent and mixins fail, throw warning
+        if !parent
           warn("@inheritdoc - parent member not found", context)
           return m
         end

data/lib/jsduck/js_parser.rb

@@ -8,7 +8,7 @@ module JsDuck
   class JsParser < JsLiteralParser
     def initialize(input, options = {})
       super(input)
-      @doc_parser = DocParser.new(:js, options[:meta_tags])
+      @doc_parser = DocParser.new
       @docs = []
       @ext_namespaces = options[:ext_namespaces] || ["Ext"]
     end

data/lib/jsduck/lint.rb

@@ -13,6 +13,7 @@ module JsDuck
     # Runs the linter
     def run
       warn_globals
+      warn_no_doc
       warn_unnamed
       warn_optional_params
       warn_duplicate_params
@@ -41,6 +42,20 @@ module JsDuck
       end
     end
 
+    # print warning for each member or parameter with no name
+    def warn_no_doc
+      @relations.each do |cls|
+        if cls[:doc] == ""
+          warn(:no_doc, "No documentation for #{cls[:name]}", cls)
+        end
+      end
+      each_member do |member|
+        if member[:doc] == ""
+          warn(:no_doc, "No documentation for #{member[:owner]}##{member[:name]}", member)
+        end
+      end
+    end
+
     # print warning for each non-optional parameter that follows an optional parameter
     def warn_optional_params
       each_member do |member|

data/lib/jsduck/logger.rb

@@ -17,9 +17,13 @@ module JsDuck
         [:inheritdoc, "@inheritdoc referring to unknown class or member"],
         [:extend, "@extend or @mixin referring to unknown class"],
         [:link, "{@link} to unknown class or member"],
+        [:link_private, "{@link} to private member"],
+        [:link_ambiguous, "{@link} is ambiguous"],
+        [:link_auto, "Auto-detected link to unknown class or member"],
 
         [:alt_name, "Name used as both classname and alternate classname"],
         [:name_missing, "Member or parameter has no name"],
+        [:no_doc, "Member or class without documentation"],
         [:dup_param, "Method has two parameters with same name"],
         [:req_after_opt, "Required parameter comes after optional"],
         [:subproperty, "@param foo.bar where foo param doesn't exist"],
@@ -34,10 +38,12 @@ module JsDuck
         [:cat_class_missing, "Class is missing from categories file"],
         [:guide, "Guide is missing from --guides dir"],
       ]
-      # Turn on all warnings by default
+      # Turn off all warnings by default.
+      # This is good for testing.
+      # When running JSDuck app, the Options class enables most warnings.
       @warnings = {}
       @warning_docs.each do |w|
-        @warnings[w[0]] = true
+        @warnings[w[0]] = false
       end
 
       @shown_warnings = {}
@@ -66,11 +72,7 @@ module JsDuck
 
     # get documentation for all warnings
     def doc_warnings
-      @warning_docs.map {|w| "+#{w[0]} - #{w[1]}" } + [
-        " ",
-        "+all - to turn on all warnings (default)",
-        " ",
-      ]
+      @warning_docs.map {|w| " #{@warnings[w[0]] ? '+' : '-'}#{w[0]} - #{w[1]}" } + [" "]
     end
 
     # Prints warning message.

data/lib/jsduck/merger.rb

@@ -1,4 +1,5 @@
 require 'jsduck/logger'
+require 'jsduck/meta_tag_registry'
 
 module JsDuck
 
@@ -15,6 +16,7 @@ module JsDuck
     def initialize
       @filename = ""
       @linenr = 0
+      @meta_tags = MetaTagRegistry.instance
     end
 
     def merge(docs, code)
@@ -64,6 +66,8 @@ module JsDuck
         :method
       elsif code[:type] == :assignment && code[:right] && code[:right][:type] == :function
         :method
+      elsif doc_map[:return] || doc_map[:param]
+        :method
       else
         :property
       end
@@ -153,7 +157,6 @@ module JsDuck
         :doc => detect_doc(docs),
         :params => detect_params(docs, code),
         :return => detect_return(doc_map, name == "constructor" ? "Object" : "undefined"),
-        :template => !!doc_map[:template],
       }, doc_map)
     end
 
@@ -176,7 +179,6 @@ module JsDuck
         :owner => detect_owner(doc_map) || owner,
         :type => detect_type(:cfg, doc_map, code),
         :doc => detect_doc(docs),
-        :required => detect_required(:cfg, doc_map),
         :default => detect_default(:cfg, doc_map, code),
         :properties => detect_subproperties(docs, :cfg),
         :accessor => !!doc_map[:accessor],
@@ -192,6 +194,7 @@ module JsDuck
         :owner => detect_owner(doc_map),
         :type => detect_type(:property, doc_map, code),
         :doc => detect_doc(docs),
+        :default => detect_default(:property, doc_map, code),
         :properties => detect_subproperties(docs, :property),
       }, doc_map)
     end
@@ -222,10 +225,7 @@ module JsDuck
     def add_shared(hash, doc_map)
       hash.merge!({
         :private => !!doc_map[:private],
-        :protected => !!doc_map[:protected],
-        :static => !!doc_map[:static],
         :inheritable => !!doc_map[:inheritable],
-        :deprecated => detect_deprecated(doc_map),
         :inheritdoc => doc_map[:inheritdoc] ? doc_map[:inheritdoc].first : nil,
         :meta => detect_meta(doc_map),
       })
@@ -236,7 +236,7 @@ module JsDuck
     def create_member_id(m)
       # Sanitize $ in member names with something safer
       name = m[:name].gsub(/\$/, 'S-')
-      "#{m[:static] ? 'static-' : ''}#{m[:tagname]}-#{name}"
+      "#{m[:meta][:static] ? 'static-' : ''}#{m[:tagname]}-#{name}"
     end
 
     def detect_name(tagname, doc_map, code, name_type = :last_name)
@@ -314,11 +314,6 @@ module JsDuck
       return explicit_name == "" || explicit_name == implicit_name
     end
 
-    def detect_required(tagname, doc_map)
-      main_tag = doc_map[tagname] ? doc_map[tagname].first : {}
-      return main_tag[:optional] == false
-    end
-
     # for detecting mixins and alternateClassNames
     def detect_list(type, doc_map, code)
       if doc_map[type]
@@ -350,7 +345,7 @@ module JsDuck
     # it instead of creating a new hash.
     def build_aliases_hash(aliases, hash={})
       aliases.each do |a|
-        if a =~ /^([\w.]+)\.(\w+)$/
+        if a =~ /^(.+)\.([^.]+)$/
           if hash[$1]
             hash[$1] << $2
           else
@@ -367,17 +362,24 @@ module JsDuck
         meta[tag[:name]] = [] unless meta[tag[:name]]
         meta[tag[:name]] << tag[:doc]
       end
-      meta
-    end
 
-    def detect_deprecated(doc_map)
-      doc_map[:deprecated] ? doc_map[:deprecated].first : nil
+      meta.each_pair do |key, value|
+        tag = @meta_tags[key]
+        meta[key] = tag.to_value(tag.boolean ? true : value)
+      end
+
+      meta[:required] = true if detect_required(doc_map)
+      meta
     end
 
     def detect_singleton(doc_map, code)
       !!(doc_map[:singleton] || code[:type] == :ext_define && code[:singleton])
     end
 
+    def detect_required(doc_map)
+      doc_map[:cfg] && doc_map[:cfg].first[:optional] == false
+    end
+
     def detect_params(docs, code)
       implicit = detect_implicit_params(code)
       explicit = detect_explicit_params(docs)

data/lib/jsduck/meta_tag.rb

@@ -8,17 +8,40 @@ module JsDuck
     # Name of the tag (required)
     attr_reader :name
 
+    # The key under which to store this tag. Must be a symbol.  When
+    # not provided then :name is converted to symbol and used as key.
+    attr_accessor :key
+
+    # The text to display in member signature.  Must be a hash
+    # defining the short and long versions of the signature text:
+    #
+    #     {:long => "something", :short => "SOM"}
+    #
+    attr_reader :signature
+
     # True to include all lines up to next @tag as part of this meta-tag
     attr_reader :multiline
 
+    # True to ignore any text after the @tag, just record the
+    # existance of the tag.
+    attr_reader :boolean
+
+    # It gets passed an array of contents gathered from all meta-tags
+    # of given type. It should return the value to be stored for this
+    # meta-tag at :key. The returned value is also passed to #to_html
+    # method. Returning nil will cause the tag to be ignored. By
+    # default the contents are returned unchanged.
+    def to_value(contents)
+      contents
+    end
+
     # Override this to transform the content of meta-tag to HTML to be
     # included into documentation.
     #
-    # It gets passed an array of contents gathered from all meta-tags
-    # of given type. It should return an HTML string to inject into
-    # document.  For help in that it can use the #format method to
-    # easily support Markdown and {@link/img} tags inside the contents
-    # of meta-tag.
+    # It gets passed the value returned by #to_value method. It should
+    # return an HTML string to inject into document.  For help in that
+    # it can use the #format method to easily support Markdown and
+    # {@link/img} tags inside the contents of meta-tag.
     #
     # By default the method returns nil, which means the tag will not
     # be rendered at all.

data/lib/jsduck/meta_tag_loader.rb

@@ -1,32 +1,41 @@
 require "jsduck/meta_tag"
-require 'jsduck/author_tag'
-require 'jsduck/doc_author_tag'
 
 module JsDuck
 
-  # Loads user-defined meta-tags
+  # Loader for built-in and user-defined meta-tags.
   class MetaTagLoader
-    # instatiates builtin meta tags
+    attr_reader :meta_tags
+
     def initialize
-      @classes = MetaTag.descendants
-      @meta_tags = @classes.map {|cls| cls.new }
+      @classes = []
+      @meta_tags = []
     end
 
-    # Loads user-defined meta-tags from given paths.
-    # Returns list of meta-tag instances.
-    def load(paths)
-      paths.each do |path|
-        if File.directory?(path)
-          Dir[path+"/**/*.rb"].each do |file|
-            require(file)
-            init_remaining
-          end
-        else
-          require(path)
-          init_remaining
-        end
+    # Loads user-defined meta-tags from given path.
+    #
+    # * If path is a directory, loads all *.rb files in it.
+    # * If path is the symbol :builtins, loads the builtin
+    #   tags from ./tag dir.
+    # * Otherwise loads tags from the single file.
+    def load(path)
+      if path == :builtins
+        load(File.dirname(__FILE__) + "/tag")
+      elsif File.directory?(path)
+        # Sort paths, so they are always loaded in the same order.
+        # This is important for signatures to always be rendered in
+        # the same order.
+        Dir[path+"/**/*.rb"].sort.each {|file| load_file(file) }
+      else
+        load_file(path)
       end
-      @meta_tags
+    end
+
+    private
+
+    # Loads just one file.
+    def load_file(file)
+      require(file)
+      init_remaining
     end
 
     # Instantiates meta tag classes that haven't been instantiated
@@ -37,12 +46,20 @@ module JsDuck
       MetaTag.descendants.each do |cls|
         if !@classes.include?(cls)
           @classes << cls
-          newtag = cls.new
+          newtag = create_tag(cls)
           @meta_tags = @meta_tags.find_all {|t| t.name != newtag.name }
           @meta_tags << newtag
         end
       end
     end
+
+    # Instanciates tag class.
+    # When .key is missing, creates it from .name
+    def create_tag(cls)
+      tag = cls.new
+      tag.key = tag.name.to_sym unless tag.key
+      tag
+    end
   end
 
 end

data/lib/jsduck/meta_tag_registry.rb

@@ -0,0 +1,79 @@
+require 'singleton'
+require "jsduck/meta_tag_loader"
+
+module JsDuck
+
+  # Access to meta-tags
+  class MetaTagRegistry
+    include Singleton
+
+    def initialize
+      @tags = []
+      @map = {}
+    end
+
+    # Loads meta-tags from the given paths.  See MetaTagLoader#load
+    # for details.
+    #
+    # This should only be called once. Calling it twice will override
+    # the previously loaded tags.
+    def load(paths)
+      loader = MetaTagLoader.new
+      paths.each {|p| loader.load(p) }
+      register(loader.meta_tags)
+    end
+
+    # Registers MetaTag instances.
+    #
+    # NB! This is for testing purposes only, elsewhere always use #load.
+    def register(tags)
+      @tags = tags
+      register_keys
+    end
+
+    # Returns array of all available tag instances
+    def tags
+      @tags
+    end
+
+    # Accesses tag by key or name
+    def [](name)
+      @map[name]
+    end
+
+    # Returns the formatter assigned to tags
+    def formatter
+      @formatter
+    end
+
+    # Sets the doc-formatter for all tags
+    def formatter=(doc_formatter)
+      @formatter = doc_formatter
+      @tags.each {|tag| tag.formatter = doc_formatter }
+    end
+
+    # Returns array of attributes to be shown in member signatures
+    # (and in order they should be shown in).
+    def signatures
+      if !@signatures
+        @signatures = @tags.find_all(&:signature).map do |tag|
+          s = tag.signature
+          s[:key] = tag.key
+          s
+        end
+      end
+      @signatures
+    end
+
+    private
+
+    def register_keys
+      @map = {}
+      @tags.each do |tag|
+        @map[tag.key] = tag
+        @map[tag.name] = tag
+      end
+    end
+  end
+
+end