Some method arguments are no longer marked as "optional"

[alano999]

I believe this is an error, accidentally introduced when some XML was refactored approximately 4 months ago.

I believe the solution is simply to add the attribute _optional="true"_ to the <argument> elements in each of these three XML Includes in api.jquery.com ...

• /includes/duration-argument.xml
• /includes/easing-argument.xml
• /includes/complete-argument.xml

Please note that I shall not able to commit and unit test the proposed solution myself. I shall have to leave that to someone with a clear mind (my prescription medication makes my brain into mush, and anything requiring deep concentration is immensely draining).

The error exists in the current Master branch of github api.jquery.com. The current production website is correct at the moment, but if the github repository is not corrected before the next release, this error would become visible and, in my opinion, seriously degrade the quality of the documentation.

The issue is that the "duration", "easing" and "complete" attributes for several of the Effects methods (such as .animate()) are optional, but are no longer visually styled to indicate this in the documentation.

This is what the current production website shows, correctly (the square brackets indicating the "optional" nature of some attributes)...
.animate( properties [, duration] [, easing] [, complete] )

And this is what the github Master branch shows, erroneously (square brackets are missing because no attributes are present to indicate the "optional" nature of the argument) implying that all arguments are mandatory...
.animate( properties, duration, easing, complete )

Simplistically: somehow the arguments need to be re-marked as optional.

Originally, the XML for each of those three arguments had a _type="Optional"_ attribute, but these attributes have not been copied across into the refactored XML includes. I suspect that the developer had intended to apply the new style of argument instead ( _optional="true"_ ) after refactoring, but simply forgot.

I hope the proposed solution is appropriate and an experienced member of the jQuery team will implement and test the solution before the next release of the API Documentation causes an unnecessary degradation in the quality of the otherwise excellent documentation.

Sincere and kind regards,
Alan

[kswedberg]

Thanks for the report, @alano999! You were correct about both the mistake and the solution.

[alano999]

Thanks for confirming that I wasn't imagining things! I also raised another issue concerning the API Documentation's XML/XSL - over in the grunt-jquery-content repository's Master branch, but no-one has yet responded to it.

It's Issue (grunt-jquery-content) # 30, if anyone is reading this and cares to take a look at it. An invalid XSL attribute is being used (attribute is not defined in W3C's XSL2 or XSL3 specifications). Some XSL libraries ignore the error, some crash. What worries me most, though, is that the author may have been using, and innocently relying upon, a customised library that does perform an operation when that nonstandard "select" attribute is encountered.

Kind regards,
Alan