clarify assert doc entry

[lmiq]

The @assert doc entry is somewhat confusing, first appearing to encourage then discourage its use. This attempts to clarify it for the general user.

[kshyatt]

Is there a way to preserve the warning about side effects? This aspect seems important if the function opens a file or something like that.

[lmiq]

I tried to rephrase it a little to improve the proposal, and reintroduced the side-effects comment, as I didn't understand that it referred to something technical and specific. I am not sure if the general user will understand the "side-effects" part.

[LilithHafner]

@assert 7 throws. Perhaps we should mention @assert expr will throw unless expr evaluates to true.