JSDoc question

[Michael O'Shaughnessy]

OK, I am improving in my coding by trying to follow good coding practices such as using namespaces and libraries.  I am still using the Google Apps Editor (not ready to make the move to VSCode, but hopefully in the near future!!) and I am stuck on documenting my code with JSDoc.  I can document basic functions but my code is more complex with namespaces and functions that take an object as a parameter and I need to find a way to properly document them.  I have looked on line for some examples but I seem to get lost...

So, here is a "sample" of what I think is correct.  If anyone can comment and let me know if it is or what needs to be fixed OR even better if you have a simple example you could share I would appreciate it!

/**

* My example namespace

* @namespace example

*/

const example = (() => {

/**

* Changes text to upper case.

*

* @param {string} inText The text to change to upper case

* @return {string} The result of the upper case function

*

*@memberof example

*/

function _toUpper(inText) {

return inText.toUpperCase();

}

/**

* Calcluate the area given width and heigth

*

* @param {obj} dimensions Object that has width and height

* @param {num} dimensions.width The width

* @param {num} dimensions.height The height

* @return {num} The area

*

* @memberof example

*/

const _calcArea = (dimensions)=>{

let x = dimensions.width

let y = dimensions.height

return x*y

}

return{

toUpper:_toUpper,

calcArea: _calcArea

}

})()

If this is good, how do I make code completion work for calcArea to show the object needs a "width" and "height"?

Thanks in advance for helping this budding programmer get better!

Michael

[dimud...@gmail.com]

The following should work:

/**

 * @typedef {Object} Dimensions

 *

 * @property {Number} width The width

 * @property {Number} height The height

 */

/**

 * My example namespace

 *

 * @namespace example

 */

const example = (() => {

    /**

     * Changes text to upper case.

     *

     * @param {String} inText The text to change to upper case

     * @return {String} The result of the upper case function

     */

    function toUpper(inText) {

        return inText.toUpperCase();

    }

    /**

     * Calculate the area given width and height.

     *

     * @param {Dimensions} dimensions

     *

     * @return {Number} area

     */

    function calcArea({ width, height }) {

        return width * height;

    }

    return {

        toUpper,

        calcArea

    };

})();

The new IDE uses Monaco, the same underlying code editor that drives VS Code, so it supports many of the same JSDoc elements that enable code completion. Such as typedef (which I used to define Dimensions as a custom type). See Typescript JSDoc documentation linked below(the subset of annotations discussed are all applicable to GAS):
https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html 

[Michael O'Shaughnessy]

Awesome!  Thank you so much!  I did look at the link you provided before and it did not make sense to me.

BUT, with just that little bit of documentation you added "@typedef" makes sense to me now.

I knew it would be simple, just could not wrap my head around it.

Thanks!

--
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 on the web visit https://groups.google.com/d/msgid/google-apps-script-community/d44fc178-d1c6-48a5-bd1b-c68646947922n%40googlegroups.com.

[Remco Edelenbos]

I cannot seem to get the formatting correct in google groups. Can you share a post or a way to do it?

[Remco Edelenbos]

And with this you will have autocomplete for like 90% of apps script in VS code.

[Michael O'Shaughnessy]

Remco, yes I have seen the typescript addition to VSCode to get autocomplete.  I have made several attempts to get VSCode going on my Chromebook BUT for my main use of Google Apps Script I never know what device I will be using at any given time.  I could be doing Professional Development at a school and will be using their devices or consulting with a superintendent and will need to use their device so I really need to be able to code 100% online.  I know GitHub has GitPod and to me it looks promising.

I really, really, really hope that Google will somehow update the GAS editor to be more like VSCode.... but I am not holding my breath!!!

To view this discussion on the web visit https://groups.google.com/d/msgid/google-apps-script-community/80bf819c-f530-473d-b3e5-cd6d7af8114en%40googlegroups.com.