Jsdoc with a library

[Michael O'Shaughnessy]

Hello everyone,

First thanks to all of you who have helped me become a better "coder"!!  

And because of that, I am trying to use "namespaces" to keep my code clearer and easier to maintain.  The issue I am running into is that I do not know how to use JSDOC correctly so autocomplete is available for the end users.

This is just a snippet of a library I am working on:

/**
 * The main shuffling code
 */
const nsShuffle = (() => {
  /**
   * Removes a column from an array
   * @param {array} arr An array of values
   * @param {integer} col The col index to get
   * @return {Array}  The one column 2d array
   */
  const getColumn_ = (arr, col) => {
    try {
      let newArr = []
      arr.forEach(r => newArr.push(r.slice(col, col + 1)))
      return newArr
    }
    catch (err) {
      logIt({
        level: "severe",
        theMsg: "getColumn issue",
        error: err
      })
    }

  }

Now "getColumns_" is "exposed" as "getColumns".  So when I go to use this library in another project I get autocomplete to show the "getColumns" is a function BUT no other info.  It show that it needs and array and integer.

Any help or guidance will be extremely appreciated!

Thanks,
Michael

[Thomas P.]

I realise this posting is from 28.Feb.2023, and it's now Dec.2024. But since zero replies has been made, I'll take a stab at it anyway.

As to GSheets, and getting custom functions to auto-complete towards end-users in the GSheet GUI, then:

Your custom functions MUST reside in the global space, i.e. there'll be no wrapping of said function into namespace, or making them nested functions.

And your custom functions (obviously) also need to be equipped with appropriate JSDocs comments, e.g.:

Example:

    /**
     * Gets the GDrive FileName of this GSheet-file,
     * @returns {string} The GDrive FileName of this GSheet-file,
     * @customfunction
    */
    function custFileName() {
      return SpreadsheetApp.getActiveSpreadsheet().getName();
    }

Well, that's how I see it, after having spent an uncomfortable amount of time, attempting to avoid cluttering up the global scope.

[Michael O'Shaughnessy]

Hello Thomas,

Ahhhhhh... global name space... OK.  Since this post I have learned a lot and now I can consistently use namespaced code in libraries BUT to do so I have learned that I need to provide a GLOBAL variable that references the library's namespace.  For example lets say I have a library with a namespace called nsSettings that obviously has code for settings.  I have to add a "var nsSettings1 = nsSettings" and then call the nsSettings1 from my the code using the library.  So...... maybe I need to add JSDoc to this global variable setting.... I will look into this when I get a chance.

Thanks,

Michael

--
You received this message because you are subscribed to the Google Groups "Google Apps Script Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to google-apps-script-c...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/google-apps-script-community/74de52e6-ffeb-4096-a71a-9d8769d88ab5n%40googlegroups.com.

[Bruce Mcpherson]

You might find this post helpful… 

https://ramblings.mcpher.com/gassnippets2/exports/

Cheers

Bruce

To view this discussion visit https://groups.google.com/d/msgid/google-apps-script-community/CAHNYQLjqExZN44BgeaO1DyUHJTizE4C3CdUc4uQOvmOxGF8EqQ%40mail.gmail.com.

[Michael O'Shaughnessy]

Thank you very much Bruce for sharing your site!!

I do have to ask, when did you post that?  It runs in my mind that I have "read" that page before.  HOWEVER it was most likely more than a year ago and at that time I had no idea what it was talking about!!

NOW that I have learned more and skills have improved I read it again and... it... makes more sense!!

I will still have to experiment BUT I understand what it is doing now!

Again, thank you so much for sharing your knowledge and expertise!!

To view this discussion visit https://groups.google.com/d/msgid/google-apps-script-community/CANijH0Vexq8R8joS%2BdYBRqKPj_iLAC2j%2BOXUupm--m2ppyJj4Q%40mail.gmail.com.

[Bruce Mcpherson]

Hi Michael

That post is indeed a few years old. However if you want some real examples with more  enhancements you can look at any recent apps script post on any of my libraries or scripts that use them. All the code is public and on GitHub.

For example.. 

https://ramblings.mcpher.com/sharing-content-not-files-with-apps-script/

Good luck and Merry Xmas

Nerve

To view this discussion visit https://groups.google.com/d/msgid/google-apps-script-community/CAHNYQLhwKnfzi_xgB384CApnU5_C%3DnKcok%3Df659LUkWREf%2B4Sw%40mail.gmail.com.