Docs: enhance documentation of existential operators

[michaelficarra]

Right now, the documentation for our existential operators is either poor or non-existent. We should list all of the following operators along with proper definitions of their behaviour and possibly individual names (taken from #1613, the issue that inspired this one):

• unary ?:
  • a? tests that a is in scope and a != null
• binary ?:
  • a ? b returns a if a is in scope and a != null; otherwise, b
• ?. and ?[ ]: soaked property access:
  • a?.b or a?['b'] returns a.b if a is in scope and a != null; otherwise, undefined
• ?( ): soaked function invocation:
  • a?(b, c) (or a? b, c) returns the result of calling a (with arguments b and c) if a is in scope and callable; otherwise, undefined
• ?=: existential assignment:
  • a ?= b assigns the value of b to a if a is not in scope or if a == null; produces the new value of a

Some particular parts of the current documentation that bother me:

• "fails for zero, the empty string, and false"
  • the list should be exhaustive or somehow acknowledge that it is not
• "returns true unless a variable is null or undefined"
  • doesn't mention how undeclared variables are handled
• doesn't really distinguish between the different operators

[jashkenas]

++, this would be great. We just need to be sure that the section doesn't get too long on the page, and still feels bite-sized.

Direct documentation patches can be committed to master, and cherry-picked over to gh-pages.

[CRogers]

Just from the viewpoint of a user, I recently tried to start using the existential operator but the docs didn't seem to correspond with what was actually happening and I ended up not using it, so +1 to this.

[tylermumford]

That's true. The documentation states that the unary ? operator checks to see if its argument is not undefined and not null, and the example compilation corresponds to that behavior: (typeof mind !== "undefined" && mind !== null). Compiling on the fly using the "Try CoffeeScript" input (which is brilliant, by the way) on the website also compiles to this code.

However, in my compilations, it leaves out undefined-checking, and simply becomes mind != null (which even has a different relational operator). Was this change made in a previous release and then missed in the documentation updates?

I'm using the Node.js executable method on Windows 7 64-bit, and coffee --version reads as "1.1.3-pre".

[michaelficarra]

Here we go again. This needs to be mentioned somewhere in the docs as well to avoid getting this question all the time.

@TylerWayne: x == null is a test for either an undefined value or null, but it's only safe to use when we know the identifier is in scope. When we can't be sure that it's in scope, we have to do the typeof test to avoid a ReferenceError.

[jashkenas]

@michaelficarra: Your patience is infinite.

I don't think that mentioning this in the docs is going to stop anyone from asking the question -- people just look at the generated output and open a ticket or comment immediately.

[tylermumford]

My apologies; thank you very much for clarifying. Yes, it would be very good to get this in the docs for novice developers like myself.

[michaelficarra]

@jashkenas: I think it may actually help. @TylerWayne said that the main source of his confusion was not the compilation itself, but the disparity between what he saw and what was listed in the documentation. It probably won't help with cases where someone sees two different compilations in their own code, not realising that one usage is on an undeclared variable, but it may help with instances like @TylerWayne's. Maybe. At the very least, it will educate people about a good javascript practice.

[showell]

+1 on better documentation, even if nobody reads it. If nothing else, when the questions come up in the future, you can point folks at the docs.

[franc]

I understand @jaskenas' reasons for wanting to keep documentation byte-sized, clear and minimalist - it speaks to what CS is all about, and is a quick and clear intro.

On the other hand it would be fantastic to have some more detailed documentation, and examples of common use etc. Perhaps the official documentation could link to a wiki page on each sub section? where we can flesh it out as a real reference rather than just a quick and powerful intro.

[wmayner]

Big +1 for this, particularly regarding the part that says

CoffeeScript's existential operator ? returns true unless a variable is null or undefined, which makes it analogous to Ruby's nil?

…which is very confusing to the less experienced among us. Maybe just a couple of sentences right after that paragraph? Something like:

Note: the ? operator only checks for null or undefined if the variable in question isn't declared. If it is declared, then it only checks if the variable is null, since the variable is already known to be in scope.

And then maybe some code blocks showing that

declared = 0
declared?
undeclared?

compiles to

var declared;
declared = 0;
declared != null;
typeof undeclared !== "undefined" && undeclared !== null;

Incidentally, I'm in favor of a complete, authoritative reference to go along with the intro docs—but I think this particular declared/undeclared thing is confusing enough that it warrants at least some mention even in the concise version.

[ymeine]

But declared != null; also checks if it is undefined: http://www.ecma-international.org/ecma-262/5.1/#sec-11.9.3 (points 1.a and 1.b correspond to strict comparison, and 2 and 3 to the behavior I'm mentioning)

[vendethiel]

It checks if its value is undefined, which will result in a TypeError if the variable isn't declared.

[ymeine]

@Nami-Doc yes, I was just telling that the documentation addition suggested by @wmayner was not correct in fact

However I noticed this exact behavior (the TypeError) while doing some tests, and now I understand why CoffeeScript compiles to typeof undeclared !== "undefined" && undeclared !== null; in case it doesn't now if the reference is actually accessible or not. Thanks! :)

(so if something should be added to the documentation, I think that would be that.)

[wmayner]

@ymeine Thanks for that correction; I didn't realize that. In that case, I'm with you—some mention of that behavior should be in the documentation, perhaps even just a footnote.

[GeoffreyBooth]

Done in #4536.