solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/tag/aside.rb

@@ -0,0 +1,71 @@
+require "jsduck/tag/tag"
+require "jsduck/logger"
+
+module JsDuck::Tag
+  class Aside < Tag
+    def initialize
+      @pattern = "aside"
+      @tagname = :aside
+      @repeatable = true
+      @html_position = POS_ASIDE
+    end
+
+    # Parses: @aside [ guide | video| example ] name
+    def parse_doc(p, pos)
+      {
+        :tagname => :aside,
+        :type => aside_type(p),
+        :name => p.hw.ident,
+      }
+    end
+
+    def aside_type(p)
+      p.look(/\w+/) ? p.ident.to_sym : nil
+    end
+
+    def process_doc(h, tags, pos)
+      h[:aside] = tags
+    end
+
+    def to_html(context)
+      context[:aside].map do |aside|
+        type = aside[:type]
+        name = aside[:name]
+        assets_group = get_assets_group(type)
+        asset = assets_group[name]
+        if asset
+          url = "#!/#{type}/#{name}"
+          heading = type.to_s.capitalize
+          title = asset["title"]
+          icon_url = assets_group.icon_url(asset)
+          <<-EOHTML
+            <div class='aside #{type}'>
+              <h4>#{heading}</h4>
+              <p><a href='#{url}'><img src='#{icon_url}' alt=''> #{title}</a></p>
+            </div>
+          EOHTML
+        else
+          warn("Unknown @aside name: #{type} #{name}", context)
+        end
+      end.compact
+    end
+
+    # special accessor for @aside alone through which assets are set
+    attr_accessor :assets
+
+    def get_assets_group(type)
+      case type
+      when :guide then @assets.guides
+      when :video then @assets.videos
+      when :example then @assets.examples
+      else {}
+      end
+    end
+
+    def warn(msg, context)
+      JsDuck::Logger.warn(:aside, msg, context[:files][0])
+      nil
+    end
+
+  end
+end

data/lib/jsduck/tag/author.rb

@@ -0,0 +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> ...
+    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/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, pos)
+      {: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,79 @@
+require "jsduck/tag/member_tag"
+require "jsduck/doc/subproperties"
+
+module JsDuck::Tag
+  class Cfg < MemberTag
+    def initialize
+      @pattern = "cfg"
+      @tagname = :cfg
+      @repeatable = true
+      @member_type = {
+        :title => "Config options",
+        :toolbar_title => "Configs",
+        :position => MEMBER_POS_CFG,
+        :icon => File.dirname(__FILE__) + "/icons/cfg.png",
+        :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, pos)
+      tag = p.standard_tag({
+          :tagname => :cfg,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
+
+      # don't parse (required) after subproperties
+      unless tag[:name] =~ /\./
+        tag[:optional] = false if parse_required(p)
+      end
+
+      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[:type] = p[:type]
+      h[:default] = p[:default]
+      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
+
+    def process_code(code)
+      h = super(code)
+      h[:type] = code[:type]
+      h[:default] = code[:default]
+      h[:accessor] = code[:accessor]
+      h[:evented] = code[:evented]
+      h
+    end
+
+    # Do the merging of :type field
+    def merge(h, docs, code)
+      if h[:type] == nil
+        h[:type] = code[:tagname] == :method ? "Function" : "Object"
+      end
+    end
+
+    def to_html(cfg, cls)
+      member_link(cfg) + " : " + cfg[:html_type]
+    end
+  end
+end

data/lib/jsduck/tag/chainable.rb

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

data/lib/jsduck/tag/class.rb

@@ -0,0 +1,77 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Class < Tag
+    def initialize
+      @pattern = "class"
+      @tagname = :class
+      @class_icon = {
+        :small => File.dirname(__FILE__) + "/icons/class.png",
+        :large => File.dirname(__FILE__) + "/icons/class-large.png",
+        :redirect => File.dirname(__FILE__) + "/icons/class-redirect.png",
+        :priority => PRIORITY_CLASS,
+      }
+    end
+
+    # @class name
+    def parse_doc(p, pos)
+      {
+        :tagname => :class,
+        :name => p.ident_chain,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:name] = tags[0][:name]
+    end
+
+    # Although class is not a member, it also has the auto-detected
+    # part from code. So this method gets called by Merger.
+    #
+    # If we did detect code as a class use all the auto-detected
+    # fields, otherwise use only the name field.
+    def process_code(code)
+      if code[:tagname] == :class
+        code
+      else
+        {:name => code[:name] }
+      end
+    end
+
+    def merge(h, docs, code)
+      # Ensure the empty members array.
+      h[:members] = []
+      # Ignore extending of the Object class
+      h[:extends] = nil if h[:extends] == "Object"
+      # Default alternateClassNames list to empty array
+      h[:alternateClassNames] = [] unless h[:alternateClassNames]
+      # Turn :aliases field into hash
+      h[:aliases] = build_aliases_hash(h[:aliases] || [])
+
+      # Takes the :enum always from docs, but the :doc_only can come
+      # from either code or docs.
+      if docs[:enum]
+        h[:enum] = docs[:enum]
+        h[:enum][:doc_only] = docs[:enum][:doc_only] || (code[:enum] && code[:enum][:doc_only])
+      end
+    end
+
+    private
+
+    # Given array of full alias names like "foo.bar", "foo.baz"
+    # build hash like {"foo" => ["bar", "baz"]}
+    def build_aliases_hash(aliases)
+      hash={}
+      aliases.each do |a|
+        if a =~ /^([^.]+)\.(.+)$/
+          if hash[$1]
+            hash[$1] << $2
+          else
+            hash[$1] = [$2]
+          end
+        end
+      end
+      hash
+    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, pos)
+      {
+        :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/component.rb

@@ -0,0 +1,19 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  # The @component tag should be rarely used explicitly as it gets
+  # auto-detected by Process::Components for any component inheriting
+  # from Ext.Component.
+  class Component < BooleanTag
+    def initialize
+      @pattern = "component"
+      @class_icon = {
+        :small => File.dirname(__FILE__) + "/icons/component.png",
+        :large => File.dirname(__FILE__) + "/icons/component-large.png",
+        :redirect => File.dirname(__FILE__) + "/icons/component-redirect.png",
+        :priority => PRIORITY_COMPONENT,
+      }
+      super
+    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, pos)
+      {: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,31 @@
+require "jsduck/tag/member_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 < MemberTag
+    def initialize
+      @tagname = :css_mixin
+      @member_type = {
+        :title => "CSS Mixins",
+        :position => MEMBER_POS_CSS_MIXIN,
+        :icon => File.dirname(__FILE__) + "/icons/css_mixin.png"
+      }
+    end
+
+    def process_code(code)
+      h = super(code)
+      h[:params] = code[:params]
+      h
+    end
+
+    def merge(h, docs, code)
+      JsDuck::ParamsMerger.merge(h, docs, code)
+    end
+
+    def to_html(mixin, cls)
+      member_link(mixin) + member_params(mixin[:params])
+    end
+  end
+end

data/lib/jsduck/tag/css_var.rb

@@ -0,0 +1,50 @@
+require "jsduck/tag/member_tag"
+
+module JsDuck::Tag
+  class CssVar < MemberTag
+    def initialize
+      @pattern = "var"
+      @tagname = :css_var
+      @member_type = {
+        :title => "CSS Variables",
+        :toolbar_title => "CSS Vars",
+        :position => MEMBER_POS_CSS_VAR,
+        :icon => File.dirname(__FILE__) + "/icons/css_var.png"
+      }
+    end
+
+    # @var {Type} [name=default] ...
+    def parse_doc(p, pos)
+      p.standard_tag({
+          :tagname => :css_var,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
+    end
+
+    def process_doc(h, tags, pos)
+      p = tags[0]
+      h[:name] = p[:name]
+      h[:type] = p[:type]
+      h[:default] = p[:default]
+    end
+
+    def process_code(code)
+      h = super(code)
+      h[:type] = code[:type]
+      h[:default] = code[:default]
+      h
+    end
+
+    # Set default value for :type field
+    def merge(h, docs, code)
+      h[:type] = "Object" unless h[:type]
+    end
+
+    def to_html(var, cls)
+      member_link(var) + " : " + var[:html_type]
+    end
+  end
+end