No documentation on asterisks

[taoeffect]

There needs to be documentation on asterisks, in one of the first paragraphs of the main Readme.

It is not at all clear to anyone new to generators in javascript what they are for, or that they are associated in any way with something called "generators", whether they represent new syntax or not, etc.

The status quo results in unnecessary wasted time for many people.

Here's some documentation about the topic, but even after reading it, I'm still unclear as to whether these symbols are necessary or not.

[tj]

will do, but yup they're necessary

[jonathanong]

i was working on a better readme but the draft i ended up with wasn't much of an improvement so i scraped it. can you list some specific stuff you are confused about? i know there have been a bunch of blog posts - maybe the best parts or ah-hah moments of those would help too.

[reqshark]

just make sure to talk about spacing and astrixises, that's where i personally need guidance. I also have a suspicion of generator relationship with the new domains of node API lore. if some comparison therein could be made kudos

[taoeffect]

@jonathanong acknowledging them before they are used would be a good start, along with an explanation of what they mean, how they are supposed to be used, their significance and any gotchas (what versions of node support them? what OS's support them? what about browsers? what's the future? etc.)

[jonathanong]

what spacing? and it has nothing to do with domains.

[reqshark]

well i meant the space and the astrixis

[reqshark]

domains are more like generators in general that's very different.

[jonathanong]

are we talking about function *() {} vs. function *(){}? i'm not sure what you mean by spacing.

[reqshark]

that helps

[jonathanong]

OH you meant in comparison to domains. i thought you implied that they were related haha

[reqshark]

they are yes wtf is domain.run() versus yield

[tj]

domains == huge hack to catch errors, yield == language-provided non-hack to write synchronous code and also happens to let you catch errors with try/catch

[tj]

other than the error aspect they're unrelated, but I would never use them

[reqshark]

thats exactly what i was asking

[jonathanong]

honestly i don't know much about domains. they seem very confusing to me. co is closer to fibers than domains.

from what i understand about domains, they catch "uncaught exceptions" and errors emitted from event emitters versus co-generators which use traditional try/catch blocks.

one caveat though with co-generators is that event emitters without any error listeners will still throw and kill your process, which is what half the issues in koa are currently about

[tj]

yea domains are basically global state, errors just get tacked to the current domain within the function, massive hack

[jonathanong]

@visionmedia perhaps we should just combine co and koa help? koajs/help#1. could make that repo a wiki where people can collaborate on docs and ask questions perhaps. maybe rename it to wiki.

everything in koajs/koa can remain dull and official.

[plievone]

are we talking about function *() {} vs. function *(){}? i'm not sure what you mean by spacing.

I guess with spacing he meant
function *() {}
function* () {}
function * () {}
function*() {}
All work.