Opened 10 years ago

Closed 9 years ago

#960 closed defect (fixed)

[raster] Start reducing number of functions by using defaults

Reported by: robe Owned by: pracine
Priority: medium Milestone: PostGIS 2.0.0
Component: raster Version: master
Keywords: Cc:

Description

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).

Change History (13)

comment:1 Changed 10 years ago by 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]);

comment:2 Changed 10 years ago by 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.

comment:3 Changed 10 years ago by pracine

Summary: Start reducing number of functions by using defaults[raster] Start reducing number of functions by using defaults

comment:4 Changed 10 years ago by Bborie Park

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

comment:5 Changed 10 years ago by 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

comment:6 Changed 10 years ago by 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.

comment:7 Changed 10 years ago by 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

comment:8 Changed 10 years ago by robe

corrected ST_AsGDALRaster doco to be consistent with implementation at r7300

comment:9 Changed 10 years ago by robe

ditto for ST_AsPNG at r7301

comment:10 Changed 9 years ago by pracine

Which other function should use default parameter?

comment:11 Changed 9 years ago by Bborie Park

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

comment:12 Changed 9 years ago by 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

comment:13 Changed 9 years ago by robe

Resolution: fixed
Status: newclosed

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

Note: See TracTickets for help on using tickets.