Generate Friendly Error Messaging from existing documentation #759

Closed
therewasaguy opened this Issue Jun 19, 2015 · 4 comments

Comments

Projects
None yet
4 participants
@therewasaguy
Member

therewasaguy commented Jun 19, 2015

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

This comment has been minimized.

Show comment
Hide comment
@workergnome

workergnome Jun 19, 2015

Contributor

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

Contributor

workergnome commented Jun 19, 2015

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

This comment has been minimized.

Show comment
Hide comment
@therewasaguy

therewasaguy Jun 19, 2015

Member

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).

Member

therewasaguy commented Jun 19, 2015

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

This comment has been minimized.

Show comment
Hide comment
@workergnome

workergnome Jun 19, 2015

Contributor

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?

Contributor

workergnome commented Jun 19, 2015

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

This comment has been minimized.

Show comment
Hide comment
@lmccart

lmccart Oct 4, 2015

Member

aggregated into #971

Member

lmccart commented Oct 4, 2015

aggregated into #971

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment