maintenance/jsduck/custom_tags.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     match = /\A([^\s]+)( .*)?\Z/m.match(tag)
  76
  77     if match
  78       name = match[1]
  79       doc = match[2] ? ': ' + match[2] : ''
  80       return formatter.format("{@link #{name}} #{doc}")
  81     else
  82       JsDuck::Logger.warn(nil, 'Unexpected @see argument: "' + tag + '"', position)
  83       return tag
  84     end
  85   end
  86 end
  87
  88 class ContextTag < CommonTag
  89   def initialize
  90     @tagname = :context
  91     @pattern = 'context'
  92     super
  93   end
  94
  95   def format(context, formatter)
  96     position = context[:files][0]
  97     context[@tagname].each do |tag|
  98       tag[:doc] = render_long_context(tag[:doc], formatter, position)
  99     end
 100   end
 101
 102   def to_html(context)
 103     <<-EOHTML
 104       <h3 class="pa">Context</h3>
 105       #{ context[@tagname].last[:doc] }
 106     EOHTML
 107   end
 108
 109   def render_long_context(tag, formatter, position)
 110     match = /\A([^\s]+)/m.match(tag)
 111
 112     if match
 113       name = match[1]
 114       return formatter.format("`context` : {@link #{name}}")
 115     else
 116       JsDuck::Logger.warn(nil, 'Unexpected @context argument: "' + tag + '"', position)
 117       return tag
 118     end
 119   end
 120 end