maintenance/jsduck/CustomTags.rb

   1 # Custom tags for JSDuck 5.x
   2 # See also:
   3 # - https://github.com/senchalabs/jsduck/wiki/Tags
   4 # - https://github.com/senchalabs/jsduck/wiki/Custom-tags
   5 # - https://github.com/senchalabs/jsduck/wiki/Custom-tags/7f5c32e568eab9edc8e3365e935bcb836cb11f1d
   6 require 'jsduck/tag/tag'
   7
   8 class CommonTag < JsDuck::Tag::Tag
   9   def initialize
  10     @html_position = POS_DOC + 0.1
  11     @repeatable = true
  12   end
  13
  14   def parse_doc(scanner, position)
  15     if @multiline
  16       return { :tagname => @tagname, :doc => :multiline }
  17     else
  18       text = scanner.match(/.*$/)
  19       return { :tagname => @tagname, :doc => text }
  20     end
  21   end
  22
  23   def process_doc(context, tags, position)
  24     context[@tagname] = tags
  25   end
  26
  27   def format(context, formatter)
  28     context[@tagname].each do |tag|
  29       tag[:doc] = formatter.format(tag[:doc])
  30     end
  31   end
  32 end
  33
  34 class SourceTag < CommonTag
  35   def initialize
  36     @tagname = :source
  37     @pattern = "source"
  38     super
  39   end
  40
  41   def to_html(context)
  42     context[@tagname].map do |source|
  43       <<-EOHTML
  44         <h3 class='pa'>Source</h3>
  45         #{source[:doc]}
  46       EOHTML
  47     end.join
  48   end
  49 end
  50
  51 class SeeTag < CommonTag
  52   def initialize
  53     @tagname = :see
  54     @pattern = "see"
  55     super
  56   end
  57
  58   def format(context, formatter)
  59     position = context[:files][0]
  60     context[@tagname].each do |tag|
  61       tag[:doc] = '<li>' + render_long_see(tag[:doc], formatter, position) + '</li>'
  62     end
  63   end
  64
  65   def to_html(context)
  66     <<-EOHTML
  67       <h3 class="pa">Related</h3>
  68       <ul>
  69       #{ context[@tagname].map { |tag| tag[:doc] }.join("\n") }
  70       </ul>
  71     EOHTML
  72   end
  73
  74   def render_long_see(tag, formatter, position)
  75     if tag =~ /\A([^\s]+)( .*)?\Z/m
  76       name = $1
  77       doc = $2 ? ': ' + $2 : ''
  78       return formatter.format("{@link #{name}} #{doc}")
  79     else
  80       JsDuck::Logger.warn(nil, 'Unexpected @see argument: "'+tag+'"', position)
  81       return tag
  82     end
  83   end
  84 end
  85
  86 class ContextTag < CommonTag
  87   def initialize
  88     @tagname = :context
  89     @pattern = 'context'
  90     super
  91   end
  92
  93   def format(context, formatter)
  94     position = context[:files][0]
  95     context[@tagname].each do |tag|
  96       tag[:doc] = render_long_context(tag[:doc], formatter, position)
  97     end
  98   end
  99
 100   def to_html(context)
 101     <<-EOHTML
 102       <h3 class="pa">Context</h3>
 103       #{ context[@tagname].last[:doc] }
 104     EOHTML
 105   end
 106
 107   def render_long_context(tag, formatter, position)
 108     if tag =~ /\A([^\s]+)/m
 109       name = $1
 110       return formatter.format("`context` : {@link #{name}}")
 111     else
 112       JsDuck::Logger.warn(nil, 'Unexpected @context argument: "'+tag+'"', position)
 113       return tag
 114     end
 115   end
 116 end