Документация по полиморфным функциям в Google Apps Script

Question

Я хочу, чтобы моя библиотечная функция работала двумя способами, в зависимости от того, был ли предоставлен второй параметр.
Например:

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

Теперь, как я должен документировать это, чтобы это выглядело так:

Эта статья не охватывает эту проблему: http://googleappsdeveloper.blogspot.de/2012/05/introducing-versions-and-libraries-in.html

Answer 1

У вас есть ограниченное подмножество тегов jsdoc для работы в Apps-скрипте, и это один из примеров, где нет способа дублировать результаты, которые вы видите в документации по сервисам. Вот список зарегистрированных проблем с поддержкой jsdoc в apps-script.

Единственное, что вы сможете сделать в приложении-скрипте, это предоставить подробную документацию о необязательных параметрах в ваших комментариях. К сожалению, это не поможет с автозаполнением.

Вот пример, основанный на том, Как просмотреть комментарии jsdoc в сценариях Google Doc, которые используют таблицы html для имитации вывода @param теги и документирует два варианта метода. Снимок экрана взят из 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[]
}