How to preview jsdoc comments in google doc scripts

Question

I know that Issue 1731 has been raised requesting preview of jsdoc within the Google script editor. http://code.google.com/p/google-apps-script-issues/issues/detail?id=1731

While we wait for that to be implemented, what's the best way to preview jsdoc comments that I'm adding to my published library, without requiring me to create a new version?

Answer 1

Update 2014: With libraries now supported by the Google Apps Script editor's autocompletion, it's possible to get immediate feedback about SOME of your library's jsdoc comments.

---

This solution isn't ideal - it doesn't provide the same look as published google script libraries - but at least I can work through my jsdoc comments to get a good idea of what they will look like, without constantly creating new versions of my library with no functional enhancements. If someone can detail the additional steps to get the exact output we'd see from publishing, please share!

This is what I've done on a Windows 7 PC. Similar steps may work on other platforms, ymmv.

• Get jsdoc3 by downloading the repository as a zipfile.

• Uncompress into a convenient location. I used C:\jsdoc. This also installs the Rhino jvm that is needed by jsdoc3.

Next, you need to get your google script into a local file that can be parsed by jsdoc3. Again, if anyone knows a better way, I'm all ears!

• Set up a local directory for your google script project. C:\myscript, say.

• Go to your script in google docs / drive / whatever, and copy the whole thing to the system clipboard.

  <ctrl-A> <ctrl-C>
  

• Using your favorite text editor, paste the clipboard contents

  <ctrl-V>
  

• Save the results in a javascript file. C:\myscript\testing.js, say.

Alright, from here it's a matter of parsing the file, auditing the output, and editing your jsdoc comments until you're happy with them.

Output of jsdoc3 will go into an "out" directory.

• Open a command window in C:\myscript.

• Parse your javascript file.

  \jsdoc\jsdoc testing.js
  

• Open the output in your default browser.

  out\index.html
  

• Rinse and repeat, until you have your desired results.

• Copy & paste your edited script back into Google space, validate that your code hasn't broken, and make a new version to generate the documentation for your published library.

Caveats:

• The format of the output is different than you'll see in a published Google Script Libary, but the content is largely the same. Remember that only a subset of jsdoc tags are supported by Google (@param and @returns only) - you can put others in your code, but they will be ignored.

• HTML tables can be included in your jsdoc comments, with limited customization options.

  • You must enclose ALL rows in <tbody></tbody> tags; rows within <thead> get ignored.
  • Further - all <th> get ignored. To make the first row stand out, use <b></b> tags.
  • Don't bother with any cell formatting, align etc. will be ignored.
  • You can specify width within a style attribute, and it survives.

Example:

Here's an example of some elements that render in both jsdoc and googlescript doc:

/**
 * Demonstrate jsdoc with a table. Otherwise, meaningless gibberish.
 *
 * <table> 
 * <tbody>
 * <tr><td style="width: 75%"><b>Student Name</b></td><td style="width: 25%"><b>Idiocy Factor</b></td></tr>
 * <tr><td> John Smith      </td><td align=right>  18 </td></tr>
 * <tr><td> Sally Doe       </td><td align=right>  53 </td></tr>
 * <tr><td> Carmen Sandiego </td><td align=right>  90 </td></tr>
 * <tr><td> Tam O'Shanter   </td><td align=right> 180 </td></tr>
 * </tbody>
 * </table>
 *
 * Continuation of function description down here. Why not have an example?
 * <pre>
 * =myFunc($A8, $DV8 )
 * </pre>
 *
 * @param {String} your mother's name, e.g. <code>"Anne Murray"</code>
 * @param {String} date of birth, <code>DD/MM/YYYY</code>
 * @returns {Date} estimated date of demise
 * @returns {String} "Please try again." if error in input
 */

Not perfect, and with a fairly high PITA value. Still, jsdoc will make sure you get the syntax of any unsupported tags right, great for portability.