[Numpy-discussion] concatenate, doc-string

[Arnd Baecker]

On Wed, 26 Apr 2006, Sasha wrote:

> On 4/26/06, David M. Cooke <cookedm at physics.mcmaster.ca> wrote:
> > ....
> > Here's what I just checked in:
> >
> >     concatenate((a1, a2, ...), axis=None) joins arrays together
> >
> >     The tuple of sequences (a1, a2, ...) are joined along the given axis
> >     (default is the first one) into a single numpy array.
> >
> >     Example:
> >
> >     >>> concatenate( ([0,1,2], [5,6,7]) )
> >     array([0, 1, 2, 5, 6, 7])
> >
>
> The first argument does not have to be a tuple:
>
> >>> print concatenate([[0,1,2], [5,6,7]])
> [0 1 2 5 6 7]
>
> but the docstring is probably ok given that the alternative is
> "sequence of sequences" ...

Seems to be the usual problem of either being slightly unprecise
but understandable or legally correct but impossible to understand
(in particular for beginners).

What about changing the example to:
"""
Examples:

>>> concatenate(([0, 1, 2], [5, 6, 7]))
array([0, 1, 2, 5, 6, 7])

>>> concatenate([[0, 1, 2], [5, 6, 7]])
array([0, 1, 2, 5, 6, 7])

>>> z =  arange(5)
>>> concatenate(([0, 1, 2], [5, 6, 7], z))
array([0, 1, 2, 5, 6, 7, 0, 1, 2, 3, 4])
"""

Best, Arnd