[raster] ST_AddBand documentation is inconsistent with function definitions and spec

[robe]

I went to install the raster_comments and get this error:

psql:share/contrib/postgis-2.0/raster_comments.sql:92: ERROR: function st_addband(raster, integer, raster, integer) does not exist

That is the documented one. But the one it should be I guess is:

st_addband(raster1 raster, raster2 raster, nband1 integer, nband2 integer);

But note: that the ST_addband function doesn't follow your convention of band number always immediately following the raster when present so the doc follows the convention but doesn't exist.

rast1,band1,rast2,band2

However your spec defines this: 7) ST_AddBand(rast1 raster, rast2 raster, band int, index int) ;

I have no idea what index is supposed to represent.

So anyrate you've got 3 things at odds with each other and I'm not sure which one is the preferred

[pracine]

So what do you prefer?:

st_addband(torast raster, fromrast raster, fromband integer, toband integer);

or

st_addband(torast raster, toband integer, fromrast raster, fromband integer);

I first planned the first version because toband is really an optional argument, but as robe mentionned it does not follow the convention that band number should follow the raster. I was happy with this exception since toband do not refer to an existing band and that it is really optionnal.

[pracine]

Actually the last form I came with to be consistent with other ST_AddBand forms is:

st_addband(torast raster, fromrast raster, fromband int, torastindex int)

Index is what we use to specify a band position when it does not exist. It is an index (a position where to add a band) not an existing band parameter.

I'll commit this...

[robe]

I changed the documentation so think we are set with this.