--- /dev/null
+# 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
"--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",
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