Document System.write/print(object) return value

[PureFox48]

Although System.Write(object) and System.print(object) both return their arguments, which is useful for method chaining etc., this isn't documented. The aim of this PR is therefore to remedy that.

[mhermier]

Is there really a use of chaining with these methods, since it possibly produce surprising chain of methods? I mean outputting to stream should succeed or fail. In the fancier case, it should provide a fluent interface, not chain to the passed argument.
In addition, that behavior is not consistent with other printing/writing methods.

[PureFox48]

TBH, I didn't even realize these methods returned anything until I read something @munificent said in this old Hacker News item:

I have the opposite feeling (possibly because Wren doesn't have implicit returns). Since library calls are expressions, they may as well return something useful when possible.

For example IO.print() returns its argument. That's handy for debugging the result of an intermediate expression. Say you've got:

someMethod(anotherOne(arg))

And something weird is going on. Giving IO.print() a return value lets you inject it in the middle:

someMethod(IO.print(anotherOne(arg)))

without having to hoist the subexpression out.

So, the use case is perhaps method injection for debugging purposes rather than method chaining and that makes sense to me.

[mhermier]

I think that theses are 2 separated functionality/concerns and should be decoupled. As this, I think, it provides a too rough debugging interface to be really usable even in the expressed/desired context. I suspect most users reason about it as a terminal expression. Not to mention, it allow to produce surprising expression like: System.print(42.3).floor Minimalism is nice, but what is the point if we need to relearn all the behaviors of the usual names.

[PureFox48]

Although I have some sympathy with what you're saying - i certainly didn't expect these methods to return anything - the fact remains that this facility has been there for at least 8 years and, as people may be using it and there is an argument for doing so from Bob himself, we can't just remove it now.

Perhaps we should just leave it undocumented though I'll wait and see what @ruby0x1 thinks before withdrawing the PR.