Ralf Hemmecke wrote:
>
> On 11/02/2015 05:54 PM, Prof. Dr. Johannes Grabmeier FW wrote:
>
> > Am 02.11.15 um 17:46 schrieb Waldek Hebisch:
> >> I do not know what more could we do to make
> >> clear that 'delete!' is a version of 'delete' that may
> >> be used when you do not care what happens to the
> >> argument (for examples because you will forget the
> >> argument and only use returned value).
>
> The point is that unless the docstring explicitly says so, it is always
> unsafe to use the variable that was given in the arguments. So even when
> a in an array and i an integer,
>
> a.i:=x
>
> is equivalent to
>
> setelt!(a, i, x)
>
> in other words, one shouldn't trust a anymore.
>
> The docstring for setelt! in PrimitiveArray comes from here.
>
> https://github.com/fricas/fricas/blob/master/src/algebra/aggcat.spad#L835
>
> and says this
>
> setelt! : (%, Dom, Im) -> Im
> ++ setelt!(u, x, y) sets the image of x to be y under u,
> ++ assuming x is in the domain of u.
> ++ Error: if x is not in the domain of u.
>
> So, yes, the setelt! is certainly a special case, but is that docstring
> really so telling that is says that u is *not* garbage after application
> of setelt! ?
Well, note that some docstring says "destructively", other like
'setelt!' only say that argument is modified. We have about 300
signatures with '!' at the end of name. Quick look at the
list indicates that destructive operation normally have
the word "destructively" in the docstring, but there seem
to be some inconsistencies.
> Furthermore, as Waldek mentioned, "destructive" operation means
> "potentially destructive", i.e., it might not destructively modify it's
> argument(s) at all. Well, no programmer would probably implement setelt!
> in a functional way (no side effects), but according what Waldek cited
> from ug01:
>
> This actually means that it is {\it allowed} to update its
> arguments but it is not {\it required} to do so.
>
> such an implementation would not contradict this general principle and
> not the docstring of setelt!. Yes, I call this a bug.
Well, 'ug01' is about general convention. Docstring can say more
an in case of 'setelt!' it does.
> And as for improving the 'delete!' docstring. I believe that programmers
> who don't know all the library conventions by heart certainly
> appreciate, if there were a sentence that explicitly states which of the
> argument is destructively modified and maybe even in which way (as would
> be necessary for setelt!).
>
> delete! : (%, Integer) -> %
> ++ delete!(u, i) destructively deletes the \spad{i}th element of u.
>
> Better perhaps
>
> ++ delete!(u, i) returns a structure v that is u without the
> ++ \spad{i}th element.
> ++ It is unsafe to use the first argument after the call.
I think it is better to make sure that the word 'destructively'
is used consistently. Putting extra wording in a single
docstring (or in few) will cause false impression that other
functions behave differently.
Also, let me note that due to overloading and type/package
distinctions we freqently have several signatures doing
essentially to same thing (but with small twists). Each
signature gets its docsting. This couses duplication.
To be managable, extended information should be outside of
docstrings and docstings should be short.
--
Waldek Hebisch
--
You received this message because you are subscribed to the Google Groups
"FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.
