Generate Friendly Error Messaging from existing documentation

[therewasaguy]

Right now, Friendly Error Messaging only happens if we add _validateParameters() inside a function and fill out the arguments to validate. For example, it's been added to the ellipse function here.

We should be able to get all the data we need from the documentation that already exists for each function. For example, here.

The documentation is converted to json when we run grunt yui - it generates a data.json file with data like this:

        {
            "file": "src/core/2d_primitives.js",
            "line": 161,
            "description": "Draws an ellipse (oval) to the screen. An ellipse with equal width and\nheight is a circle. By default, the first two parameters set the location,\nand the third and fourth parameters set the shape's width and height. The\norigin may be changed with the ellipseMode() function.",
            "itemtype": "method",
            "name": "ellipse",
            "params": [
                {
                    "name": "a",
                    "description": "x-coordinate of the ellipse.",
                    "type": "Number"
                },
                {
                    "name": "b",
                    "description": "y-coordinate of the ellipse.",
                    "type": "Number"
                },
                {
                    "name": "c",
                    "description": "width of the ellipse.",
                    "type": "Number"
                },
                {
                    "name": "d",
                    "description": "height of the ellipse.",
                    "type": "Number"
                }
            ],

I'm trying to think through if/how this could be incorporated into the build process. I think if we can figure that out it would make this great initiative more sustainable.

[workergnome]

Half of me thinks this is a fantastic idea. The other half of me thinks of all of the terrible, terrible ways this could break.

That being said, I think what you're talking about doing is running a custom parser over the codebase at compile time through grunt. After running the yuidocs. It totally could be done. Regexes and string insertion. Overloaded functions and our use of automatic type casting is the only thing that worries me.

✨ SOO MUCH MAGIC ✨

[therewasaguy]

Good thinkin @workergnome . For example, how would we handle the save method? Could this be accomplished by really good, clear documentation?

Maybe there should still be a flag to turn on (or off) Friendly Errors in case it brings up issues with overloaded functions...and maybe that defeats the purpose of auto-generating the parameter details from the docs.

But I like the idea that our efforts should just go into making the documentation really solid, and that powers everything else (online docs, error checking, auto-complete in the editors, etc).

[workergnome]

Worth looking at issue #755, as well. I'm OK with spamming someone if there's a real problem, but we should figure out how to not do that for other people.

Speculating, but what we're talking about here is a type system for our applications. Issue #583, through closed, might be a big help in this. I don't know much about Typescript, but would it help with something like this?

[lmccart]

aggregated into #971