From 094eca5bbfde65047d12d2a49e4d86c7a85467a1 Mon Sep 17 00:00:00 2001
From: "James D. Forrester" <jforrester@wikimedia.org>
Date: Fri, 11 Apr 2014 15:41:50 -0700
Subject: [PATCH] Support JSDuck v5.x

Add support to JSDuck v5.x with a new "CustomTags.rb" following the new
format (and with a new name for one of the existing flags). Also works
for JSDuck v4.x as before. The call in maintenance/mwjsduck-gen is now
sync'ed with the call made by Jenkins in the CI environment.

Change-Id: Ie6649a3e39457bde7a0d8bd00da8ea53e76e3085
---
 maintenance/jsduck/CustomTags.rb | 116 +++++++++++++++++++++++++++++++
 maintenance/jsduck/config.json   |   2 -
 maintenance/mwjsduck-gen         |  12 +++-
 3 files changed, 127 insertions(+), 3 deletions(-)
 create mode 100644 maintenance/jsduck/CustomTags.rb

diff --git a/maintenance/jsduck/CustomTags.rb b/maintenance/jsduck/CustomTags.rb
new file mode 100644
index 0000000000..2aff98812b
--- /dev/null
+++ b/maintenance/jsduck/CustomTags.rb
@@ -0,0 +1,116 @@
+# Custom tags for JSDuck 5.x
+# 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 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 = :context
+    @pattern = 'context'
+    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("`context` : {@link #{name}}")
+    else
+      JsDuck::Logger.warn(nil, 'Unexpected @context argument: "'+tag+'"', position)
+      return tag
+    end
+  end
+end
diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json
index 0635769021..493815eba7 100644
--- a/maintenance/jsduck/config.json
+++ b/maintenance/jsduck/config.json
@@ -2,9 +2,7 @@
 	"--title": "MediaWiki core - Documentation",
 	"--footer": "Documentation for MediaWiki core. Generated on {DATE} by {JSDUCK} {VERSION}.",
 	"--categories": "./categories.json",
-	"--meta-tags": "./MetaTags.rb",
 	"--eg-iframe": "./eg-iframe.html",
-	"--warnings": ["-no_doc"],
 	"--builtin-classes": true,
 	"--output": "../../docs/js",
 	"--external": "HTMLElement,HTMLDocument,Window",
diff --git a/maintenance/mwjsduck-gen b/maintenance/mwjsduck-gen
index 4254887731..62d1bbab22 100755
--- a/maintenance/mwjsduck-gen
+++ b/maintenance/mwjsduck-gen
@@ -11,10 +11,20 @@ then
 	exit 1
 fi
 
+# Support jsduck 4.x and 5.x
+JSDUCK_VERSION="$(jsduck --version | sed -e 's/[.].*//')"
+if [  "$JSDUCK_VERSION" = "JSDuck 4" ]; then
+	JSDUCK_VERSION_OPT="--meta-tags ./maintenance/jsduck/MetaTags.rb --warnings=-no_doc"
+else
+	JSDUCK_VERSION_OPT="--tags ./maintenance/jsduck/CustomTags.rb --warnings=-nodoc(class,public)"
+fi
+
 MWCORE_DIR=$(cd $(dirname $0)/..; pwd)
 
 jsduck \
 --config=$MWCORE_DIR/maintenance/jsduck/config.json \
---footer="Documentation for MediaWiki core ($JSDUCK_MWVERSION). Generated on {DATE} by {JSDUCK} {VERSION}." \
+$JSDUCK_VERSION_OPT \
+--footer="Documentation for branch ($JSDUCK_MWVERSION) on {DATE} by {JSDUCK} {VERSION}." \
+--processes 0 --warnings-exit-nonzero \
 && echo 'JSDuck execution finished.' \
 && ln -s ../../resources $MWCORE_DIR/docs/js/modules
-- 
2.20.1