jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/tag/author.rb

@@ -1,11 +1,15 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/tag"
 
 module JsDuck::Tag
-  # Implementation of hidden @author tag
-  class Author < JsDuck::MetaTag
+  class Author < Tag
     def initialize
-      @name = "author"
+      @pattern = "author"
+    end
+
+    # @author Name of Author <email@example.com> ...
+    # Everything until the end of line gets just ignored.
+    def parse_doc(p)
+      p.match(/.*$/)
     end
   end
 end
-

data/lib/jsduck/tag/boolean_tag.rb

@@ -0,0 +1,24 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # Base class for simple boolean @tags.
+  # Subclasses should only define @pattern and call #super,
+  # which will take care of setting up @tagname with the same name.
+  class BooleanTag < Tag
+    def initialize
+      if @pattern
+        @tagname = @pattern.to_sym
+      end
+    end
+
+    # Parses just the name of the tag.
+    def parse_doc(p)
+      {:tagname => @tagname}
+    end
+
+    # When the tag is found, its value will always be true.
+    def process_doc(h, docs, pos)
+      h[@tagname] = true
+    end
+  end
+end

data/lib/jsduck/tag/cfg.rb

@@ -0,0 +1,45 @@
+require "jsduck/tag/tag"
+require "jsduck/doc/subproperties"
+
+module JsDuck::Tag
+  class Cfg < Tag
+    def initialize
+      @pattern = "cfg"
+      @tagname = :cfg
+      @member_type = {
+        :name => :cfg,
+        :category => :property_like,
+        :title => "Config options",
+        :toolbar_title => "Configs",
+        :position => MEMBER_POS_CFG,
+        :subsections => [
+          {:title => "Required config options", :filter => {:required => true}},
+          {:title => "Optional config options", :filter => {:required => false}, :default => true},
+        ]
+      }
+    end
+
+    # @cfg {Type} [name=default] (required) ...
+    def parse_doc(p)
+      tag = p.standard_tag({:tagname => :cfg, :type => true, :name => true})
+      tag[:optional] = false if parse_required(p)
+      tag[:doc] = :multiline
+      tag
+    end
+
+    def parse_required(p)
+      p.hw.match(/\(required\)/i)
+    end
+
+    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]
+    end
+  end
+end

data/lib/jsduck/tag/chainable.rb

@@ -1,14 +1,12 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # Implementation of @chainable tag
-  class Chainable < JsDuck::MetaTag
+  class Chainable < BooleanTag
     def initialize
-      @name = "chainable"
-      @key = :chainable
+      @pattern = "chainable"
       @signature = {:long => "chainable", :short => "&gt;"} # show small right-arrow
-      @boolean = true
+      @css = ".signature .chainable { background-color: #00aa00 }" # green
+      super
     end
   end
 end
-

data/lib/jsduck/tag/class.rb

@@ -0,0 +1,28 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Class < Tag
+    def initialize
+      @pattern = "class"
+      @tagname = :class
+      @merge_context = :class
+    end
+
+    # @class name
+    def parse_doc(p)
+      {
+        :tagname => :class,
+        :name => p.ident_chain,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:name] = tags[0][:name]
+    end
+
+    # Ensure the empty members array.
+    def merge(h, docs, code)
+      h[:members] = []
+    end
+  end
+end

data/lib/jsduck/tag/class_list_tag.rb

@@ -0,0 +1,40 @@
+require "jsduck/tag/tag"
+require "jsduck/js/utils"
+
+module JsDuck::Tag
+  # Base class for tags like @mixins, @uses, etc
+  # Which take the following form:
+  #
+  #     @tagname classname1 classname2 ...
+  #
+  # Subclasses need to define the @patterns and @tagname fields for
+  # the #parse_doc and #process_doc methods to work. Plus
+  # @ext_define_pattern and @ext_define_default for the
+  # #parse_ext_define to work.
+  #
+  class ClassListTag < Tag
+    def parse_doc(p)
+      {
+        :tagname => @tagname,
+        :classes => classname_list(p),
+      }
+    end
+
+    # matches <ident_chain> <ident_chain> ... until line end
+    def classname_list(p)
+      classes = []
+      while cls = p.hw.ident_chain
+        classes << cls
+      end
+      classes
+    end
+
+    def process_doc(h, tags, pos)
+      h[@tagname] = tags.map {|d| d[:classes] }.flatten
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[@tagname] = JsDuck::Js::Utils.make_string_list(ast)
+    end
+  end
+end

data/lib/jsduck/tag/constructor.rb

@@ -0,0 +1,24 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Constructor < Tag
+    def initialize
+      @pattern = "constructor"
+      @tagname = :constructor
+    end
+
+    # @constructor
+    def parse_doc(p)
+      {:tagname => :constructor, :doc => :multiline}
+    end
+
+    # The method name will become "constructor" unless a separate
+    # @method tag already supplied the name.
+    def process_doc(h, tags, pos)
+      h[:name] = "constructor" unless h[:name]
+      # Documentation after @constructor is part of the constructor
+      # method top-level docs.
+      h[:doc] += tags[0][:doc]
+    end
+  end
+end

data/lib/jsduck/tag/css_mixin.rb

@@ -0,0 +1,17 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # As of now there is no @css_mixin tag available in CSS files.  This
+  # class just exists to define that we have a member type called
+  # :css_mixin.
+  class CssMixin < Tag
+    def initialize
+      @member_type = {
+        :name => :css_mixin,
+        :category => :method_like,
+        :title => "CSS Mixins",
+        :position => MEMBER_POS_CSS_MIXIN,
+      }
+    end
+  end
+end

data/lib/jsduck/tag/css_var.rb

@@ -0,0 +1,29 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class CssVar < Tag
+    def initialize
+      @pattern = "var"
+      @tagname = :css_var
+      @member_type = {
+        :name => :css_var,
+        :category => :property_like,
+        :title => "CSS Variables",
+        :toolbar_title => "CSS Vars",
+        :position => MEMBER_POS_CSS_VAR,
+      }
+    end
+
+    # @var {Type} [name=default] ...
+    def parse_doc(p)
+      p.standard_tag({:tagname => :css_var, :type => true, :name => true})
+    end
+
+    def process_doc(h, tags, pos)
+      p = tags[0]
+      h[:name] = p[:name]
+      h[:type] = p[:type]
+      h[:default] = p[:default]
+    end
+  end
+end

data/lib/jsduck/tag/default.rb

@@ -0,0 +1,31 @@
+require "jsduck/tag/tag"
+require "jsduck/docs_code_comparer"
+require "jsduck/util/html"
+
+module JsDuck::Tag
+  # There is no @default tag.
+  #
+  # Default values are detected from syntax like this:
+  #
+  #     @cfg [blah=somedefault]
+  #
+  # This tag class exists to take care of the merging of :default
+  # fields and to generate the "Defaults to:" text in final HTML.
+  class Default < Tag
+    def initialize
+      @tagname = :default
+      @merge_context = :property_like
+      @html_position = POS_DEFAULT
+    end
+
+    def merge(h, docs, code)
+      h[:default] = JsDuck::DocsCodeComparer.merge_if_matches(:default, docs, code)
+    end
+
+    def to_html(m)
+      return if m[:default] == "undefined"
+
+      "<p>Defaults to: <code>" + JsDuck::Util::HTML.escape(m[:default]) + "</code></p>"
+    end
+  end
+end

data/lib/jsduck/tag/deprecated.rb

@@ -1,33 +1,19 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/deprecated_tag"
 
 module JsDuck::Tag
-  # Implementation of @deprecated tag
-  class Deprecated < JsDuck::MetaTag
+  class Deprecated < DeprecatedTag
     def initialize
-      @name = "deprecated"
-      @key = :deprecated
-      @signature = {:long => "deprecated", :short => "DEP"}
-      @multiline = true
-    end
-
-    def to_value(contents)
-      text = contents[0]
-      if text =~ /\A([0-9.]+)(.*)\Z/
-        {:version => $1, :text => $2.strip}
-      else
-        {:text => text || ""}
-      end
-    end
-
-    def to_html(depr)
-      v = depr[:version] ? "since " + depr[:version] : ""
-      <<-EOHTML
-        <div class='signature-box deprecated'>
-        <p>This #{@context[:tagname]} has been <strong>deprecated</strong> #{v}</p>
-        #{format(depr[:text])}
-        </div>
-      EOHTML
+      @tagname = :deprecated
+      @css = <<-EOCSS
+        .signature .deprecated {
+          background-color: #aa0000;
+        }
+        .deprecated-box strong {
+          color: white;
+          background-color: #aa0000;
+        }
+      EOCSS
+      super
     end
   end
 end
-

data/lib/jsduck/tag/deprecated_tag.rb

@@ -0,0 +1,58 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # Base class for both @deprecated and @removed.  Child classes only
+  # need to define the @tagname attribute and call #super - all the
+  # correct behavior will the fall out automatically.
+  class DeprecatedTag < Tag
+    def initialize
+      if @tagname
+        @pattern = @tagname.to_s
+        @signature = {:long => @tagname.to_s, :short => @tagname.to_s[0..2].upcase}
+        @html_position = POS_DEPRECATED
+        @css += <<-EOCSS
+          .deprecated-tag-box {
+            text-align: center;
+            color: #600;
+            background-color: #fee;
+          }
+          .deprecated-tag-box strong {
+            text-transform: uppercase;
+            border-radius: 2px;
+            padding: 0 3px;
+          }
+        EOCSS
+      end
+    end
+
+    def parse_doc(p)
+      {
+        :tagname => @tagname,
+        :version => p.match(/[0-9.]+/),
+        :doc => :multiline,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      v = {:text => tags[0][:doc] || ""}
+      v[:version] = tags[0][:version] if tags[0][:version]
+      h[@tagname] = v
+    end
+
+    def format(context, formatter)
+      context[@tagname][:text] = formatter.format(context[@tagname][:text])
+    end
+
+    def to_html(context)
+      depr = context[@tagname]
+      v = depr[:version] ? "since " + depr[:version] : ""
+      <<-EOHTML
+        <div class='rounded-box #{@tagname}-box deprecated-tag-box'>
+        <p>This #{context[:tagname]} has been <strong>#{@tagname}</strong> #{v}</p>
+        #{depr[:text]}
+        </div>
+      EOHTML
+    end
+
+  end
+end

data/lib/jsduck/tag/doc.rb

@@ -0,0 +1,32 @@
+require "jsduck/tag/tag"
+require 'jsduck/format/shortener'
+
+module JsDuck::Tag
+  # A special class for rendering the documentation field inside
+  # classes and members.
+  class Doc < Tag
+    def initialize
+      @tagname = :doc
+      @html_position = POS_DOC
+      @shortener = JsDuck::Format::Shortener.new
+    end
+
+    def format(m, formatter)
+      m[:doc] = formatter.format(m[:doc])
+
+      if expandable?(m) || @shortener.too_long?(m[:doc])
+        m[:short_doc] = @shortener.shorten(m[:doc])
+      end
+    end
+
+    def to_html(m)
+      m[:doc]
+    end
+
+    private
+
+    def expandable?(m)
+      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:deprecated] || m[:template]
+    end
+  end
+end

data/lib/jsduck/tag/docauthor.rb

@@ -1,11 +1,10 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/author"
 
 module JsDuck::Tag
-  # Implementation of hidden @docauthor tag
-  class Docauthor < JsDuck::MetaTag
+  # Exactly the same as @author tag - it's simply ignored.
+  class Docauthor < Author
     def initialize
-      @name = "docauthor"
+      @pattern = "docauthor"
     end
   end
 end
-