Re: [PATCH 1/2] zshmisc(1): Clarify the documentation of 'return' and 'exit' in conjunction with try/always

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Peter Stephenson wrote on Sat, Dec 21, 2019 at 17:58:35 +0000:
> On Sat, 2019-12-21 at 12:41 +0000, Daniel Shahaf wrote:
> > Having reviewed 20076, 20084, 21734, and 21735, my understanding is that
> > the original intention was:
> > 
> > - A 'return' in a function does run always-list
> > - An 'exit' outside a function does not run always-list
> > - A 'return' outside a function is treated as an 'exit'
> > 
> > All of which are the case today.  The remaining case, of 'exit' used
> > inside a function, was not specified by the referenced -workers@ posts;
> > does, as implemented, run the always-list; and furthermore, based in
> > 21734 it's fair to assume that the original documentation was assuming
> > that 'exit' would be used outside of any function, just like it assumed
> > 'return' would be used inside a function.
> > 
> > Therefore, have the documentation specify only the behaviour of 'exit'
> > outside any function, and leave the behaviour of 'exit' inside
> > a function unspecified.  Anyone who relied on the documentation of 'exit'
> > as documented until this commit would have run into the
> > documentation/implementation discrepancy described in 45075.
> 
> That seems fine.
> 
> I don't think it would be problematic to document the current behaviour
> of exit in a functoin, actually, with the implication it won't suddenly
> change as I can't see why it would,

The documentation promised one thing and the implementation did another thing.
We can't _both_ deliver compatibility and deliver on the API promise, and
I didn't want to choose one over the other.

I certainly don't intend to change the implementation just because the
documentation said so — there's no reason to break people's code.  On the other
hand, I also want to reinforce the notion that API promises can be relied on.

> but leaving the implicit assumption that return is the standard way to get
> out of a function and otherwise you're in uncharted territory seems fine,
> too.

Yeah, it's not ideal, but using exit in a try block in a function _already is_
uncharted territory, so it seems like the lesser of three evils.

Thanks for the review,

Daniel