Polymorphic function documentation in Google Apps Script

Question

I want my library function to work in two ways, depending on whether the second parameter was provided.
For example:

function sheet_to_dict(a, b) {
  var array = (
    b ? SpreadsheetApp.openById(a).getSheetByName(b) : a
  ).getDataRange().getValues();

Now how should I document it to make it look like:

This article doesn't cover this problem: http://googleappsdeveloper.blogspot.de/2012/05/introducing-versions-and-libraries-in.html

Answer 1

You've got a limited subset of jsdoc tags to work with in Apps-script, and this is one example where there's no way to duplicate the results you see in the Services documentation. Here's a list of reported issues with the support of jsdoc in apps-script.

The only thing you'll be able to do in apps-script is to provide detailed documentation about the optional parameters in your comments. That won't help with auto-completion at all, unfortunately.

Here's an example based on How to preview jsdoc comments in google doc scripts that uses html tables to simulate the output of @param tags, and documents two variants of a method. The screenshot is from the library documentation URL, https://script.google.com/macros/library/d/<Library-Id>/<ver>.

/**
 * Does incredible things, in a number of amazing ways.
 *
 * <pre>
 * jsdocTest( var1, var2 )
 * </pre>
 * Description of the first variant.
 * <table><tbody>
 * <tr><td style="width: 20%"><b>Parameter</b></td><td style="width: 15%"><b>Type</b></td><td style="width: 65%"><b>Description</b></td></tr>
 * <tr><td> var1 </td><td> number </td><td> Description of Number Parameter </td></tr>
 * <tr><td> var2 </td><td> string </td><td> Description of String Parameter </td></tr>
 * </tbody></table>
 *
 * <pre>
 * jsdocTest( var3, var4 )
 * </pre>
 * Description of the second variant.
 * <table><tbody>
 * <tr><td style="width: 20%"><b>Parameter</b></td><td style="width: 15%"><b>Type</b></td><td style="width: 65%"><b>Description</b></td></tr>
 * <tr><td> var3 </td><td> Object </td><td> Description of Object parameter </td></tr>
 * <tr><td> var4 </td><td> String [] </td><td> Description of String Array </td></tr>
 * </tbody></table>
 */
function jsdocTest () {
  // Handle all parameters via arguments[]
}