[raster] Start reducing number of functions by using defaults

[robe]

I figure I would break this out into two separate parts -- one for raster and one for core PostGIS.

I'll be starting with PostGIS, but will write that in a separate ticket.

I did decide that even though the raster functions are not written as such, that I can go ahead and start documenting them as if they did use default arguments. Down side is those other protos will not have PostgreSQL help comments generated (which is just as well because I want to remove them anyway)

So here is an example:

​http://www.postgis.org/documentation/manual-svn/RT_ST_AsTIFF.html

I am using [] for optional (though I guess with arrays its a bit confusing especially this one because of the liberal use of input arrays). I'm open to how we represent optional args.

Sadly I was only able to slash 6 of the 10 permutations of ST_AsTIFF we have (hypothetically speaking since the documentation is a prototype of what the functions should be at this point).

[pracine]

What about:

bytea ST_AsTIFF(raster rast[, text[] options][, text srs]);

instead? (with italic stating at the first bracket) This is the Python doc way.

What about the default values?:

bytea ST_AsTIFF(raster rast[, integer[] nbands=ARRAY[1]][, integer compression=""][, integer srs=sameassource]);

[robe]

I tried to use the choice='opt' feature of docbook hoping it would produce that, but that didn't seem to work. So your proposal might require us writing our own chunk.xsl which when I brought up to Kevin a while back he figuratively shook his head in a (NO WAY JOSE sort of way as it involved a lot of changing of .xsl files I guess). Does Python use docbook? Maybe I can see how they do it and copy that.

I think we can swing putting in default values. I might have to change my test scripts. I think my auto generate help comment scripts should still work fine without change since they will probably just list the default as part of the description, which would be nice anyway.

[Bborie Park]

I'll add default values for those functions that I've written thus far.

[Bborie Park]

Changes thus far...

r7259 - ST_Band

r7260 - ST_SummaryStats, ST_Count, ST_Sum, ST_Mean, ST_StdDev and ST_MinMax

r7262 - ST_Histogram

r7263 - ST_Quantile

r7264 - ST_ValueCount and ST_ValuePercent

[robe]

BBorie,

Thanks that's great. I've been slow in documenting because I'm still trying to figure out how PHP and the others get those conditional brackets in there. I suspect it's something I need to change in the Makefile.in or we need to update our docbook style sheets since even after copying their exact template it still doesn't come out right on the other end when I was using the latest docbook stylesheets I downloaded.

[Bborie Park]

All other functions that I've written have now been modified with default values for appropriate function parameters.

r7295 ST_AsGDALRaster

r7296 ST_AsTIFF, ST_AsJPEG and ST_AsPNG

[robe]

corrected ST_AsGDALRaster doco to be consistent with implementation at r7300

[robe]

ditto for ST_AsPNG at r7301

[pracine]

Which other function should use default parameter?

[Bborie Park]

Everything that can be simplified. I'd recommend starting with functions that have too many variations. Again, hopefully Regina has some suggestions.

[robe]

Looks like you have taken care of the big ones. As far as I can tell, this is all tha tis left that can be reduced.

ST_SetGeoReference
ST_SetBandIsNoData
ST_DumpAsPolygons
ST_Intersection
ST_Polygon
ST_Intersects

[robe]

I think this is pretty much done so closing it out.