Last active
February 16, 2021 16:10
-
-
Save rudimusmaximus/0ba5e091c0dee455670f9fd7fb780e07 to your computer and use it in GitHub Desktop.
GDG Lightning Talk 2020.06.11 Class Free code see comments for presentation link
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/** | |
* 'class free' object constructor for a simple counter that counts up or down | |
* | |
* @param {Object} Spec - generic object for member destructuring-assignments | |
* @param {String} Spec.runBy - name of person using the constructor | |
* @returns {{up: Function, down: Function, toJSON: Function}} | |
*/ | |
function counter_constructor(Spec) { | |
let { | |
runBy = 'John Doe', // default value if not specified | |
counter = 0, // initialize private member of state not expected in Spec | |
forgotToSay // no default; if not specified gets undefined | |
} = Spec; | |
/** | |
* private function that prints a greeting to the runBy member passed in by | |
* Spec obj or set to default value if not passed | |
*/ | |
const sayHello = () => (console.log(`Hello, ${runBy}. Let's count!`)); | |
/** | |
* Increases state counter by one | |
* @returns {boolean} | |
*/ | |
const up = () => { | |
counter += 1; | |
return true; | |
}; | |
/** | |
* Decreases state counter by one | |
* @returns {boolean} | |
*/ | |
const down = function () { | |
counter -= 1; | |
return true; | |
} | |
/** | |
* This returns an object of selected members and can be called directly or | |
* using JSON.stringify on an Object made with a _constructor | |
* (not using new keyword) | |
* | |
* @returns {Object} Snapshot - selected items for logging or debugging | |
*/ | |
const toJSON = function () { | |
let Snapshot = { | |
title: `a selective snapshot of ${counter_constructor.name}`, | |
Spec, | |
runBy, | |
forgotToSay, | |
counter, | |
up, | |
down, | |
toJSON | |
}; | |
return Object.freeze(Snapshot); | |
}; | |
sayHello(); | |
return Object.freeze({ | |
up, | |
down, | |
toJSON, | |
}); | |
} | |
const Count = counter_constructor({runBy: "rudy"}); | |
Count.up(); | |
Count.up(); | |
Count.up(); | |
Count.down(); | |
console.log('---'); | |
console.log(Count.up()); | |
console.log(Count.down()); | |
console.log('---'); | |
console.log(Count); | |
console.log('---'); | |
console.log(Count.toJSON()); | |
console.log('---'); | |
console.log(JSON.stringify(Count, null, 4)); |
The Returns JSDOC is of 'Record Type' per the Google JavaScript Style Guide
@returns {{myNum: number, myObject}}
An anonymous type with the given type members.
In our example, I used * @returns {{up: Function, down: Function, toJSON: Function}}
How to best document the methods in the anonymous record type as functions? or objects?
Comments welcome.
My IDE is WebStorm from JetBrains, I have submitted this issue "Invalid Quick Doc for properties when JSDoc record type is used" and it has been accepted.
In our example, in my IDE, autocomplete works for Count.method but the pop up doc falls back to the constructor and not the JSDOC inside the constructor for shared methods.
I will do some research on if there's a better way to document the @returns also. This is where I'm at for now.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The presentation in PDF HERE.
Recording on youtube HERE
Open for comments or suggestions, especially about the JSDOC approach. Thanks.