Better JSDoc with @example

[mesqueeb]

Note that right now "is-what" is terrible for Google SEO since even refinements like "is-what npm" or "is-what github" all are like "What is GitHub?" and "What is npm? A quick intro." instead of this package. 🤣 I think that a website would be a good idea to make a presence for Googlers and also provide valuable documentation overview that is generated from code and doesn't need to be custom-made in the readme. Specifically, examples are CRUCIAL.

open question: will this ticket cover improving the SEO?

[jcbhmr]

I am not sure if examples will improve SEO. I honestly have no idea. I just know that right now I get this kind of results:

My best guess is that having a website wit the title matching "is-what" is the best thing. The examples just give Google more content and "fullness" to flesh out the webpages themselves so that GoogleBot doesn't think "empty website, not important" and instead thinks "full website, good ranking"

[jcbhmr]

btw something I noticed: I don't think you need to duplicate JSDoc and TS type annotations 🤔

/**
 * Returns the object type of the given payload
 *
 * @param {*} payload
 * @returns {string}
 */
export function getType(payload: any): string {
  return Object.prototype.toString.call(payload).slice(8, -1)
}

can just be 👇

/**
 * Returns the object type of the given payload
 */
export function getType(payload: any): string {
  return Object.prototype.toString.call(payload).slice(8, -1)
}

[jcbhmr]

This is the kind of lackluster docs I'm talking about when I say "we should improve the docs" 😢

[jcbhmr]

I've come around to believe that having more content (i.e. examples) would also help improve SEO. Right now here's what it looks like on Google: https://www.google.com/search?q=is-what+site%3Agithub.io