solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/tag/ignore.rb

@@ -0,0 +1,12 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  # Causes a member or entire class documentation to be completely
+  # excluded from docs.
+  class Ignore < BooleanTag
+    def initialize
+      @pattern = "ignore"
+      super
+    end
+  end
+end

data/lib/jsduck/tag/inheritable.rb

@@ -0,0 +1,10 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Inheritable < BooleanTag
+    def initialize
+      @pattern = "inheritable"
+      super
+    end
+  end
+end

data/lib/jsduck/tag/inheritdoc.rb

@@ -0,0 +1,48 @@
+require "jsduck/tag/tag"
+require "jsduck/member_registry"
+
+module JsDuck::Tag
+  class Inheritdoc < Tag
+    def initialize
+      @pattern = ["inheritdoc", "inheritDoc"]
+      @tagname = :inheritdoc
+    end
+
+    # @inheritdoc class.name#static-type-member
+    def parse_doc(p, pos)
+      parse_as_inheritdoc(p)
+    end
+
+    # This separate method exits to allow it to be also called from
+    # @alias tag implementation.
+    #
+    # Matches a member reference: <class.name> "#" <static> "-" <type> "-" <member>
+    #
+    # Returns :inheritdoc tag definition with corresponding fields.
+    def parse_as_inheritdoc(p)
+      tag = {
+        :tagname => :inheritdoc,
+        :cls => p.ident_chain,
+      }
+
+      if p.look(/#\w/)
+        p.match(/#/)
+        if p.look(/static-/)
+          tag[:static] = true
+          p.match(/static-/)
+        end
+        if p.look(JsDuck::MemberRegistry.regex)
+          tag[:type] = p.match(/\w+/).to_sym
+          p.match(/-/)
+        end
+        tag[:member] = p.ident
+      end
+
+      tag
+    end
+
+    def process_doc(h, docs, pos)
+      h[:inheritdoc] = docs.first
+    end
+  end
+end

data/lib/jsduck/tag/listener.rb

@@ -0,0 +1,36 @@
+require "jsduck/tag/member_tag"
+require "jsduck/params_merger"
+
+module JsDuck::Tag
+  class Listener < MemberTag
+    def initialize
+      @pattern = "listener"
+      @tagname = :listener
+      @member_type = {
+        :title => "Listeners",
+        :position => MEMBER_POS_LISTENER,
+        :icon => File.dirname(__FILE__) + "/icons/listener.png"
+      }
+    end
+
+    # @listener name ...
+    def parse_doc(p, pos)
+      {
+        :tagname => :listener,
+        :name => p.ident,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:name] = tags[0][:name]
+    end
+
+    def merge(h, docs, code)
+      JsDuck::ParamsMerger.merge(h, docs, code)
+    end
+
+    def to_html(listener, cls)
+      member_link(listener) + member_params(listener[:params])
+    end
+  end
+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

@@ -0,0 +1,14 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Markdown < Tag
+    def initialize
+      @pattern = "markdown"
+    end
+
+    # @markdown
+    def parse_doc(p, pos)
+      # Just completely ignore this tag.
+    end
+  end
+end

data/lib/jsduck/tag/member.rb

@@ -0,0 +1,24 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Member < Tag
+    # This is an odd case where tag itself is @member, but the value
+    # of it gets stored in :owner.
+    def initialize
+      @pattern = "member"
+      @tagname = :owner
+    end
+
+    # @member classname
+    def parse_doc(p, pos)
+      {
+        :tagname => :owner,
+        :owner => p.ident_chain,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:owner] = tags[0][:owner]
+    end
+  end
+end

data/lib/jsduck/tag/member_tag.rb

@@ -0,0 +1,131 @@
+require 'jsduck/tag/tag'
+require 'jsduck/render/signature_util'
+
+module JsDuck::Tag
+  # Base class for all builtin members.
+  class MemberTag < Tag
+    # Defines a class member type and specifies various settings.  For
+    # example:
+    #
+    #     {
+    #       :title => "Events",
+    #       :position => MEMBER_POS_EVENT,
+    #       # The following are optional
+    #       :toolbar_title => "Events",
+    #       :icon => File.dirname(__FILE__) + "/icons/event.png",
+    #       :subsections => [
+    #         {:title => "Static events",
+    #          :filter => {:static => false},
+    #          :default => true},
+    #         {:title => "Instance events",
+    #          :filter => {:static => true}},
+    #       ]
+    #     }
+    #
+    # Position defines the ordering of member section in final HTML
+    # output.
+    #
+    # Title is shown at the top of each such section and also as a
+    # label on Docs app toolbar button unless :toolbar_title is
+    # specified.
+    #
+    # Icon defines a file to be used as member icon in various places
+    # of the docs app.
+    #
+    # Subsections allows splitting the list of members to several
+    # subgroups.  For example methods get split into static and
+    # instance methods.
+    #
+    # - The :filter field defines how to filter out the members for
+    #   this subcategory.  :static=>true filters out all members that
+    #   have a :static field with a truthy value.  Conversely,
+    #   :static=>false filters out members not having a :static field
+    #   or having it with a falsy value.
+    #
+    # - Setting :default=>true will hide the subsection title when all
+    #   the members end up in that subsection.  For example when there
+    #   are only instance methods, the docs will only contain the
+    #   section title "Methods", as by default one should assume all
+    #   methods are instance methods if not stated otherwise.
+    #
+    attr_reader :member_type
+
+    # Avoid already-defined-constant warnings in Ruby 1.8
+    unless defined?(MEMBER_POS_CFG)
+      MEMBER_POS_CFG = 1
+      MEMBER_POS_PROPERTY = 2
+      MEMBER_POS_METHOD = 3
+      MEMBER_POS_EVENT = 4
+      MEMBER_POS_CSS_VAR = 5
+      MEMBER_POS_CSS_MIXIN = 6
+      MEMBER_POS_LISTENER = 7
+    end
+
+    # Extracts the fields auto-detected from code that are relevant to
+    # the member type and returns a hash with them.
+    #
+    # The implementation here extracts fields applicable to all member
+    # types.  When additional member-specific fields are to be
+    # extracted, override this method, but be sure to call the
+    # superclass method too.
+    #
+    # For example inside Method tag we might additionally want to
+    # extract :type and :default:
+    #
+    #     def process_code(code)
+    #       h = super(code)
+    #       h[:type] = code[:type]
+    #       h[:default] = code[:default]
+    #       h
+    #     end
+    #
+    def process_code(code)
+      return {
+        :tagname => code[:tagname],
+        # An auto-detected name might be "MyClass.prototype.myMethod" -
+        # for member name we only want the last "myMethod" part.
+        :name => code[:name] ? code[:name].split(/\./).last : nil,
+
+        :autodetected => code[:autodetected],
+        :inheritdoc => code[:inheritdoc],
+        :static => code[:static],
+        :private => code[:private],
+        :inheritable => code[:inheritable],
+        :linenr => code[:linenr],
+      }
+    end
+
+    # Merges documentation and code hashes into the result hash.
+    def merge(hash, docs, code)
+    end
+
+    # This method defines the signature-line of the member.
+    # For example it might return something like this:
+    #
+    #     "apply(source, target) : Object"
+    #
+    # Use #member_link method to render the member name as link in a
+    # standard way.  Similarly there's helper method #member_params
+    # for rendering the parameter list.
+    def to_html(context, cls)
+    end
+
+    # Creates HTML link to the given member.
+    # A helper method for use in #to_html.
+    def member_link(member)
+      JsDuck::Render::SignatureUtil::link(member[:owner], member[:id], member[:name])
+    end
+
+    # Creates HTML listing of parameters.
+    # When called with nil, creates empty params list.
+    # A helper method for use in #to_html.
+    def member_params(params)
+      ps = Array(params).map do |p|
+        p[:optional] ? "[#{p[:name]}]" : p[:name]
+      end.join(", ")
+
+      "( <span class='pre'>#{ps}</span> )"
+    end
+
+  end
+end

data/lib/jsduck/tag/method.rb

@@ -0,0 +1,75 @@
+require "jsduck/tag/member_tag"
+require "jsduck/params_merger"
+
+module JsDuck::Tag
+  # Implementation of @method tag.
+  class Method < MemberTag
+    def initialize
+      @pattern = "method"
+      @tagname = :method
+      @member_type = {
+        :title => "Methods",
+        :position => MEMBER_POS_METHOD,
+        :icon => File.dirname(__FILE__) + "/icons/method.png",
+        :subsections => [
+          {:title => "Instance methods", :filter => {:static => false}, :default => true},
+          {:title => "Static methods", :filter => {:static => true}},
+        ]
+      }
+    end
+
+    # @method name ...
+    def parse_doc(p, pos)
+      {
+        :tagname => :method,
+        :name => p.ident,
+      }
+    end
+
+    # Onle sets the name when it's actually specified.
+    # Otherwise we might overwrite name coming from @constructor.
+    def process_doc(h, tags, pos)
+      h[:name] = tags[0][:name] if tags[0][:name]
+    end
+
+    def process_code(code)
+      h = super(code)
+      h[:params] = code[:params]
+      h[:chainable] = code[:chainable]
+      h[:fires] = code[:fires]
+      h[:method_calls] = code[:method_calls]
+      h
+    end
+
+    def merge(h, docs, code)
+      JsDuck::ParamsMerger.merge(h, docs, code)
+    end
+
+    def to_html(m, cls)
+      new_kw(m) + method_link(m, cls) + member_params(m[:params]) + return_value(m)
+    end
+
+    private
+
+    def new_kw(m)
+      constructor?(m) ? "<strong class='new-keyword'>new</strong>" : ""
+    end
+
+    def method_link(m, cls)
+      if constructor?(m)
+        member_link(:owner => m[:owner], :id => m[:id], :name => cls[:name])
+      else
+        member_link(m)
+      end
+    end
+
+    def constructor?(m)
+      m[:name] == "constructor"
+    end
+
+    def return_value(m)
+      m[:return] ? (" : " + m[:return][:html_type]) : ""
+    end
+
+  end
+end

data/lib/jsduck/tag/mixins.rb

@@ -0,0 +1,27 @@
+require "jsduck/tag/class_list_tag"
+
+module JsDuck::Tag
+  class Mixins < ClassListTag
+    def initialize
+      @pattern = ["mixin", "mixins"]
+      @tagname = :mixins
+      @repeatable = true
+      @ext_define_pattern = "mixins"
+      @ext_define_default = {:mixins => []}
+    end
+
+    # Override definition in parent class.  In addition to Array
+    # literal, mixins can be defined with an object literal.
+    def parse_ext_define(cls, ast)
+      cls[:mixins] = to_mixins_array(ast)
+    end
+
+    # converts AstNode, whether it's a string, array or hash into
+    # array of strings (when possible).
+    def to_mixins_array(ast)
+      v = ast.to_value
+      mixins = v.is_a?(Hash) ? v.values : Array(v)
+      mixins.all? {|mx| mx.is_a? String } ? mixins : []
+    end
+  end
+end