Add documentation for all JS

[bedeoverend]

• [x] simpla-img
• [x] simpla-img behaviors
• [x] simpla-img utils
• [x] sm-img-canvas
• [x] sm-img-canvas utils
• [x] sm-img-controls
• [x] sm-img-controls behaviors

[madeleineostoja]

Just found out that ESlint can lint code docs, which we should definitely do. So as you go through and comment components just add "valid-jsdoc": 2 to .eslintrc. I've been adding it below "space-infix-ops": 2,. Already added it to the generator.

By default ESlint freaks out if there's no @returns statement, and further if it doesn't have a type ({undefined} or {void} for side-effects functions). I'm still not sure which way to go with this, for example Google's Clojure compiler guidelines say if there's no return statement to omit the @returns statement, but I guess more info the better? In either case, you can turn that off if need be.

[bedeoverend]

Nice! My personal preference is to include a @returns statement. But, that's just my opinion, I'll add it in as I go

[madeleineostoja]

kewl. Yeah I prefer including @returns too, can't hurt to have too much info, and if it's missing you have to dig through the function to see if it returns anything to make sure it wasn't just left out of the docs.

[bedeoverend]

@seaneking do you want to look over the docs PRs, or happy for me to merge?

[madeleineostoja]

couple of linting errors ;-)

@returns has to have a type, if it's for side-effects only make it {undefined}

And things like properties should use // Comment syntax rather than JsDoc, otherwise it'll be subject to linting (needs @returns etc.)

[bedeoverend]

@seaneking haha, yeah just a few. I think my linter must be broken. I'll let you know when I've patched it up

[bedeoverend]

@seaneking could you take a look to see if linting is passing on yours now too? I've left the /** syntax for properties in, as it's cleaner IMO and passes my linter. Maybe only cares about @returns before functions? Hopefully anyway, otherwise that's just confusing.

[madeleineostoja]

:+1: lgtm