jenkins-bot has submitted this change and it was merged. Change subject: Improve JSDuck ......................................................................
Improve JSDuck Import tags and externals, and related jscsrc change, from Echo. Change-Id: I788275e5d26652f23665c9d1a27a9a457780386b --- M .jscsrc A jsduck.external.js A jsduck.json A jsduck_custom_tags.rb 4 files changed, 165 insertions(+), 1 deletion(-) Approvals: Catrope: Looks good to me, approved jenkins-bot: Verified diff --git a/.jscsrc b/.jscsrc index 9d22e3f..70e9673 100644 --- a/.jscsrc +++ b/.jscsrc @@ -1,3 +1,22 @@ { - "preset": "wikimedia" + "preset": "wikimedia", + "jsDoc": { + "checkAnnotations": { + "preset": "jsduck5", + "extra": { + "mixin": false, + "todo": true, + "see": true + } + }, + "requireParamTypes": true, + "checkReturnTypes": true, + "checkParamNames": true, + "checkTypes": "strictNativeCase", + "requireReturnTypes": true, + "checkRedundantAccess": true, + "checkRedundantParams": true, + "checkRedundantReturns": true, + "requireNewlineAfterDescription": true + } } diff --git a/jsduck.external.js b/jsduck.external.js new file mode 100644 index 0000000..5a9a22c --- /dev/null +++ b/jsduck.external.js @@ -0,0 +1,49 @@ +/** + * Source: <http://api.jquery.com/> + * @class jQuery + */ + +/** + * Source: <http://api.jquery.com/jQuery.ajax/> + * @method ajax + * @static + * + * @return {jqXHR} + */ + +/** + * Source: <http://api.jquery.com/Types/#Event> + * @class jQuery.Event + */ + +/** + * Source: <http://api.jquery.com/Types/#Promise> + * @class jQuery.Promise + */ + +/** + * Source: <http://api.jquery.com/jQuery.Deferred/> + * @class jQuery.Deferred + * @mixins jQuery.Promise + */ + +/** + * Source: <http://api.jquery.com/Types/#jqXHR> + * @class jQuery.jqXHR + * @alternateClassName jqXHR + */ + +/** + * Source: <https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api> + * @class mw.Api + */ + +/** + * Source: <https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Message + * @class mw.Message + */ + +/** + * Source: <https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title> + * @class mw.Title + */ diff --git a/jsduck.json b/jsduck.json new file mode 100644 index 0000000..04fede7 --- /dev/null +++ b/jsduck.json @@ -0,0 +1,13 @@ +{ + "--title": "PageTriage - Documentation", + "--processes": "0", + "--warnings-exit-nonzero": true, + "--external": "OO.*", + "--output": "docs", + "--tags": "jsduck_custom_tags.rb", + "--": [ + "jsduck.external.js", + "modules", + "tests" + ] +} diff --git a/jsduck_custom_tags.rb b/jsduck_custom_tags.rb new file mode 100644 index 0000000..6a4da00 --- /dev/null +++ b/jsduck_custom_tags.rb @@ -0,0 +1,83 @@ +# 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 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) + match = tag.match(/\A([^\s]+)( .*)?\Z/m) + if match + name = match[1] + doc = match[2] ? ': ' + match[2] : '' + return formatter.format("{@link #{name}} #{doc}") + else + JsDuck::Logger.warn(nil, 'Unexpected @see argument: "' + tag + '"', position) + return tag + end + end +end + +class TodoTag < CommonTag + def initialize + @tagname = :todo + @pattern = 'todo' + super + end + + def to_html(context) + <<-EOHTML + <h3>TODO</h3> + #{context[@tagname].last[:doc]} + EOHTML + end +end -- To view, visit https://gerrit.wikimedia.org/r/311866 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: I788275e5d26652f23665c9d1a27a9a457780386b Gerrit-PatchSet: 2 Gerrit-Project: mediawiki/extensions/PageTriage Gerrit-Branch: master Gerrit-Owner: Mattflaschen <mflasc...@wikimedia.org> Gerrit-Reviewer: Catrope <r...@wikimedia.org> Gerrit-Reviewer: Mattflaschen <mflasc...@wikimedia.org> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits