Cscott has uploaded a new change for review. https://gerrit.wikimedia.org/r/81273
Change subject: Updates to support jsduck 5.x. ...................................................................... Updates to support jsduck 5.x. Change-Id: I16123e91370cb6a7785060c749530953f4c3ddf4 --- A .docs/CustomTags.rb M .docs/MetaTags.rb M .docs/config.json M .docs/generate.sh M CODING.md 5 files changed, 182 insertions(+), 6 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/VisualEditor refs/changes/73/81273/1 diff --git a/.docs/CustomTags.rb b/.docs/CustomTags.rb new file mode 100644 index 0000000..24dc1cb --- /dev/null +++ b/.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 diff --git a/.docs/MetaTags.rb b/.docs/MetaTags.rb index 22e0f3b..5e0a415 100644 --- a/.docs/MetaTags.rb +++ b/.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 diff --git a/.docs/config.json b/.docs/config.json index 958d83c..94ce5bc 100644 --- a/.docs/config.json +++ b/.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, diff --git a/.docs/generate.sh b/.docs/generate.sh index e0c7a3b..6756df9 100755 --- a/.docs/generate.sh +++ b/.docs/generate.sh @@ -16,8 +16,19 @@ 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/[.].*//'g)" +if [ "$jsduckver" = "JSDuck 3" -o "$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 diff --git a/CODING.md b/CODING.md index baf1ede..11480ec 100644 --- a/CODING.md +++ b/CODING.md @@ -55,11 +55,8 @@ Once you have gem, installing [JSDuck](https://github.com/senchalabs/jsduck) is easy: ``` -$ 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 -- To view, visit https://gerrit.wikimedia.org/r/81273 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I16123e91370cb6a7785060c749530953f4c3ddf4 Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/extensions/VisualEditor Gerrit-Branch: master Gerrit-Owner: Cscott <canan...@wikimedia.org> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
