Titanium JIRA Archive
Titanium SDK/CLI (TIMOB)

[TIMOB-9799] APIDoc: Need way to identify varargs

GitHub Issuen/a
TypeNew Feature
PriorityMedium
StatusClosed
ResolutionFixed
Resolution Date2012-08-14T13:38:41.000+0000
Affected Version/sRelease 2.0.1
Fix Version/sSprint 2012-16 Core, Release 3.0.0
ComponentsTooling
Labelscore
ReporterArthur Evans
AssigneeArthur Evans
Created2012-06-25T23:05:51.000+0000
Updated2012-11-26T21:55:29.000+0000

Description

Would be good to add a format for this. JSDuck supports varargs so we can translate straight through for that format. It appears to be supported in JSCA as well, using the "usage" field, which can be "required," "optional," "zero-or-more," or "one-or-more." Perhaps we could just add a field to the parameter description like repeatable: true or vararg: true?

Comments

  1. Bill Dawson 2012-08-07

    @ARTHUR: Do you happen to know one of the API methods with a varargs? I can't think of any off the top of my head, and it would be good for testing.
  2. Bill Dawson 2012-08-08

    @ARTHUR: Also, do you think we'll need to specify some kind of typed varargs (i.e., varargs, but each element must be a particular type)? Or is just plain old varargs enough?
  3. Arthur Evans 2012-08-09

    @BILL: Sorry for the late response. I think typed varargs would be good. Maybe just a flag to the parameter that says it's repeatable. This should be easy to map to the JsDuck or Google Closure compiler type.
  4. Bill Dawson 2012-08-13

    TDoc spec update to review: https://wiki.appcelerator.org/display/guides2/TDoc+Specification#TDocSpecification-MethodParameterSpecification
  5. Bill Dawson 2012-08-13

    Testing docgen.py html generation

    * Open apidoc/Titanium/Titanium.yml in your bestest most favoritest editor in the wholesy worldsy. (aka vi). * Find the documentation for the method named include. * Add repeatable: true to include's name parameter. * Save. * Run python apidoc/docgen.py. * When it's finished, open dist/apidoc/index.html in a browser. * Navigate to the Titanium module's include documentation. * For the name argument you should see "..." after its name and "Repeatable" at the end of its summary.

    Testing docgen.py jsca generation

    * Edit Titanium.yml per above if you haven't already (i.e., add repeatable: true to the name parameter of the include method.) * Run python apidoc/docgen.py -f jsca -o dist/apidoc. * When it's finished, open dist/apidoc/api.jsca in a text editor. * Use the text editor to search for "one-or-more". * You should find "usage": "one-or-more" on the entry for the name parameter of the include method.

    Testing validate.py

    * Edit Titanium.yml per above if you haven't already (i.e., add repeatable: true to the name parameter of the include method.) * Run python apidoc/validate.py -e -s simple. There should be no errors reported concerning the use of repeatable. * Change the value of the repeatable parameter in Titanium.yml's include method from true to abc (an invalid value.) * Run python apidoc/validate.py -e -s simple. You should get an error telling you that "repeatable" should be either true or false.
  6. Bill Dawson 2012-08-13

    @ARTHUR: Not sure if you'll like what I generate in HTML for this. But I guess our html generator is kinda irrelevant now that we use jsduck, right?
  7. Bill Dawson 2012-08-13

    PR ready: https://github.com/appcelerator/titanium_mobile/pull/2719
  8. Arthur Evans 2012-08-14

    Testing docgen.py jsduck generation

    * The String.yml file is updated in my PR so you can test with that. * Run python apidoc/docgen.py -f jsduck -o dist/apidoc. * When it's finished, open dist/apidoc/titanium.js in a text editor. * Use the text editor to search for "@method format". * You should find * @param {String/Number...} value in the entry for the format method.
  9. Arthur Evans 2012-08-14

    PR Ready: https://github.com/appcelerator/titanium_mobile/pull/2742
  10. Natalie Huynh 2012-11-26

    Tested with 3.0.0.v20121121161553

JSON Source