maintenance/jsduck/custom_tags.rb

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