Updates to support jsduck 5.x

Change-Id: I16123e91370cb6a7785060c749530953f4c3ddf4

.docs/CustomTags.rb

@@ -0,0 +1,168 @@
+# See also:
+# - https://github.com/senchalabs/jsduck/wiki/Tags
+# - https://github.com/senchalabs/jsduck/wiki/Custom-tags
+# - https://github.com/senchalabs/jsduck/wiki/Custom-tags/7f5c32e568eab9edc8e3365e935bcb836cb11f1d
+require 'jsduck/tag/tag'
+
+class CommonTag < JsDuck::Tag::Tag
+  def initialize
+    @html_position = POS_DOC + 0.1
+    @repeatable = true
+  end
+
+  def parse_doc(scanner, position)
+    if @multiline
+      return { :tagname => @tagname, :doc => :multiline }
+    else
+      text = scanner.match(/.*$/)
+      return { :tagname => @tagname, :doc => text }
+    end
+  end
+
+  def process_doc(context, tags, position)
+    context[@tagname] = tags
+  end
+
+  def format(context, formatter)
+    context[@tagname].each do |tag|
+      tag[:doc] = formatter.format(tag[:doc])
+    end
+  end
+end
+
+class SourceTag < CommonTag
+  def initialize
+    @tagname = :source
+    @pattern = "source"
+    super
+  end
+
+  def to_html(context)
+    context[@tagname].map do |source|
+      <<-EOHTML
+        <h3 class='pa'>Source</h3>
+        #{source[:doc]}
+      EOHTML
+    end.join
+  end
+end
+
+class UntilTag < CommonTag
+  def initialize
+    @tagname = :until
+    @pattern = "until"
+    super
+  end
+
+  def to_html(context)
+    <<-EOHTML
+      <h3>Until</h3>
+      <div class="signature-box"><p>
+      This method provides <strong>browser compatibility</strong> for:
+      #{ context[@tagname].map {|tag| tag[:doc] }.join("\n") }
+      </p></div>
+    EOHTML
+  end
+end
+
+class SeeTag < CommonTag
+  def initialize
+    @tagname = :see
+    @pattern = "see"
+    super
+  end
+
+  def format(context, formatter)
+    position = context[:files][0]
+    context[@tagname].each do |tag|
+      tag[:doc] = '<li>' + render_long_see(tag[:doc], formatter, position) + '</li>'
+    end
+  end
+
+  def to_html(context)
+    <<-EOHTML
+      <h3 class="pa">Related</h3>
+      <ul>
+      #{ context[@tagname].map {|tag| tag[:doc] }.join("\n") }
+      </ul>
+    EOHTML
+  end
+
+  def render_long_see(tag, formatter, position)
+    if tag =~ /\A([^\s]+)( .*)?\Z/m
+      name = $1
+      doc = $2 ? ': ' + $2 : ''
+      return formatter.format("{@link #{name}} #{doc}")
+    else
+      JsDuck::Logger.warn(nil, 'Unexpected @see argument: "'+tag+'"', position)
+      return tag
+    end
+  end
+end
+
+class ContextTag < CommonTag
+  def initialize
+    @tagname = :this
+    @pattern = 'this'
+    super
+  end
+
+  def format(context, formatter)
+    position = context[:files][0]
+    context[@tagname].each do |tag|
+      tag[:doc] = render_long_context(tag[:doc], formatter, position)
+    end
+  end
+
+  def to_html(context)
+    <<-EOHTML
+      <h3 class="pa">Context</h3>
+      #{ context[@tagname].last[:doc] }
+    EOHTML
+  end
+
+  def render_long_context(tag, formatter, position)
+    if tag =~ /\A([^\s]+)/m
+      name = $1
+      return formatter.format("`this` : {@link #{name}}")
+    else
+      JsDuck::Logger.warn(nil, 'Unexpected @this argument: "'+tag+'"', position)
+      return tag
+    end
+  end
+end
+
+class EmitsTag < CommonTag
+  def initialize
+    @tagname = :emits
+    @pattern = 'emits'
+    super
+  end
+
+  def format(context, formatter)
+    position = context[:files][0]
+    context[@tagname].each do |tag|
+      tag[:doc] = '<li>' + render_long_event(tag[:doc], formatter, position) + '</li>'
+    end
+  end
+
+  def to_html(context)
+    <<-EOHTML
+      <h3 class="pa">Emits</h3>
+      <ul>
+      #{ context[@tagname].map {|tag| tag[:doc] }.join("\n") }
+      </ul>
+    EOHTML
+  end
+
+  def render_long_event(tag, formatter, position)
+    if tag =~ /\A(\w+)( .*)?\Z/m
+      name = $1
+      doc = $2 ? ': ' + $2 : ''
+      return formatter.format("{@link #event-#{name}} #{doc}")
+    else
+      JsDuck::Logger.warn(nil, 'Unexpected @emits argument: "'+tag+'"', position)
+      return tag
+    end
+  end
+end

.docs/MetaTags.rb

@@ -1,6 +1,7 @@
 # See also:
 # - https://github.com/senchalabs/jsduck/wiki/Tags
 # - https://github.com/senchalabs/jsduck/wiki/Custom-tags
+# - https://github.com/senchalabs/jsduck/wiki/Custom-tags/7f5c32e568eab9edc8e3365e935bcb836cb11f1d
 require 'jsduck/meta_tag'
 
 class SourceTag < JsDuck::MetaTag

.docs/config.json

@@ -1,7 +1,6 @@
 {
 	"--title": "VisualEditor Code Documentation",
 	"--categories": "../.docs/categories.json",
-	"--meta-tags": "../.docs/MetaTags.rb",
 	"--eg-iframe": "../.docs/eg-iframe.html",
 	"--warnings": ["-no_doc"],
 	"--builtin-classes": true,

.docs/generate.sh

@@ -16,8 +16,19 @@ cd $(cd $(dirname $0); pwd)
 	done
 ) < eg-iframe.tpl | php > eg-iframe.html
 
+# allow custom path to jsduck, or custom version (eg JSDUCK=jsduck _4.10.4_)
+JSDUCK=${JSDUCK:-jsduck}
+
+# Support jsduck 4.x and 5.x
+jsduckver="$($JSDUCK --version | sed -e 's/[.].*//')"
+if [  "$jsduckver" = "JSDuck 4" ]; then
+	jsduckopt="--meta-tags ../.docs/MetaTags.rb"
+else
+	jsduckopt="--tags ../.docs/CustomTags.rb"
+fi
+
 # Disable parallel processing which seems to be causing problems under Ruby 1.8
-jsduck --config=config.json --processes=0 --color --warnings-exit-nonzero
+$JSDUCK --config config.json $jsduckopt --processes 0 --color --warnings-exit-nonzero
 ec=$?
 
 rm eg-iframe.html

CONTRIBUTING.md

@@ -71,12 +71,9 @@ If you've never used `gem` before, don't forget to add the gem's bin to your
 
 Once you have gem, installing [JSDuck](https://github.com/senchalabs/jsduck) is easy:
 ```sh
-$ gem install --user-install jsduck --version '< 5'
+$ gem install --user-install jsduck
 ```
 
-You need to make sure that you are using jsduck 4.x, as jsduck 5.x introduced
-incompatible changes to custom tags.
-
 ### Running jsduck
 
 Creating the documentation is easy: