Krinkle has uploaded a new change for review. https://gerrit.wikimedia.org/r/108053
Change subject: [WIP] Support JSDuck v5.x ...................................................................... [WIP] Support JSDuck v5.x Experimental, don't merge! Wikimedia Jenkins still uses JSDuck v4.x for now. This is in preparation for a future upgrade for local usage by developers. * The CustomTags.rb file is based on MetaTags.rb, except using the new JsDuck::Tag::Tag interface that has replaced the old JsDuck::MetaTag interface from JSDuck v4. * The @emits plugin was not ported since that is part of JSDuck core starting at v5. Also: * Fixed bug in maintenance/mwjsduck-gen where it would create mediawiki-core/resources/resources/ -> ../resources if you ran it twice in a row because ln -s doesn't account for the symlink already existing and pointing to another directory, in which case it creates the symlink inside of that directory, in this case the same directory it is pointing to. Change-Id: I3c7a06b0df6a5a29d591d470baedf9d0b7b0b85c --- A maintenance/jsduck/CustomTags.rb M maintenance/mwjsduck-gen 2 files changed, 136 insertions(+), 5 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core refs/changes/53/108053/1 diff --git a/maintenance/jsduck/CustomTags.rb b/maintenance/jsduck/CustomTags.rb new file mode 100644 index 0000000..346079b --- /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 = :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 diff --git a/maintenance/mwjsduck-gen b/maintenance/mwjsduck-gen index 622712e..cd9a268 100755 --- a/maintenance/mwjsduck-gen +++ b/maintenance/mwjsduck-gen @@ -13,9 +13,24 @@ 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}." \ -&& echo 'JSDuck execution finished.' +# Allow custom path to jsduck, or custom version (eg JSDUCK=jsduck _4.10.4_) +JSDUCK=${JSDUCK:-jsduck} -ln -s ../../resources $MWCORE_DIR/docs/js/modules +# Support jsduck 4.x and 5.x +jsduckver="$($JSDUCK --version | sed -e 's/[.].*//')" +if [ "$jsduckver" = "JSDuck 4" ]; then + jsduckopt="--meta-tags $MWCORE_DIR/maintenance/jsduck/MetaTags.rb" +else + jsduckopt="--tags $MWCORE_DIR/maintenance/jsduck/CustomTags.rb" +fi + +$JSDUCK --config $MWCORE_DIR/maintenance/jsduck/config.json $jsduckopt \ +--warnings-exit-nonzero \ +--footer "Documentation for MediaWiki core ($JSDUCK_MWVERSION). Generated on {DATE} by {JSDUCK} {VERSION}." \ +&& echo 'JSDuck execution finished.' +ec=$? + +test ! -L $MWCORE_DIR/docs/js/modules && ln -s ../../resources $MWCORE_DIR/docs/js/modules || echo 'Symlink already exists' + +# Exit with exit code of jsduck command +exit $ec -- To view, visit https://gerrit.wikimedia.org/r/108053 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I3c7a06b0df6a5a29d591d470baedf9d0b7b0b85c Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/core Gerrit-Branch: master Gerrit-Owner: Krinkle <krinklem...@gmail.com> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
