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 SourceTag < CommonTag
  34   def initialize
  35     @tagname = :source
  36     @pattern = 'source'
  37     super
  38   end
  39
  40   def to_html(context)
  41     context[@tagname].map do |source|
  42       <<-EOHTML
  43         <h3 class='pa'>Source</h3>
  44         #{source[:doc]}
  45       EOHTML
  46     end.join
  47   end
  48 end
  49
  50 class SeeTag < CommonTag
  51   def initialize
  52     @tagname = :see
  53     @pattern = 'see'
  54     super
  55   end
  56
  57   def format(context, formatter)
  58     position = context[:files][0]
  59     context[@tagname].each do |tag|
  60       tag[:doc] = '<li>' + render_long_see(tag[:doc], formatter, position) + '</li>'
  61     end
  62   end
  63
  64   def to_html(context)
  65     <<-EOHTML
  66       <h3 class="pa">Related</h3>
  67       <ul>
  68       #{context[@tagname].map { |tag| tag[:doc] }.join("\n")}
  69       </ul>
  70     EOHTML
  71   end
  72
  73   def render_long_see(tag, formatter, position)
  74     match = /\A([^\s]+)( .*)?\Z/m.match(tag)
  75
  76     if match
  77       name = match[1]
  78       doc = match[2] ? ': ' + match[2] : ''
  79       return formatter.format("{@link #{name}} #{doc}")
  80     else
  81       JsDuck::Logger.warn(nil, 'Unexpected @see argument: "' + tag + '"', position)
  82       return tag
  83     end
  84   end
  85 end
  86
  87 class ContextTag < CommonTag
  88   def initialize
  89     @tagname = :context
  90     @pattern = 'context'
  91     super
  92   end
  93
  94   def format(context, formatter)
  95     position = context[:files][0]
  96     context[@tagname].each do |tag|
  97       tag[:doc] = render_long_context(tag[:doc], formatter, position)
  98     end
  99   end
 100
 101   def to_html(context)
 102     <<-EOHTML
 103       <h3 class="pa">Context</h3>
 104       #{context[@tagname].last[:doc]}
 105     EOHTML
 106   end
 107
 108   def render_long_context(tag, formatter, position)
 109     match = /\A([^\s]+)/m.match(tag)
 110
 111     if match
 112       name = match[1]
 113       return formatter.format("`context` : {@link #{name}}")
 114     else
 115       JsDuck::Logger.warn(nil, 'Unexpected @context argument: "' + tag + '"', position)
 116       return tag
 117     end
 118   end
 119 end