[postgis-devel] PostGIS Development Roadmap

[Dane Springmeyer]

On Apr 21, 2008, at 9:52 PM, Kevin Neufeld wrote:

> These all sound good to me.  Can we add to this list a documentation  
> overhaul?
> Personally, I would love to see the documentation become much more  
> exhaustive in it's method descriptions (a more professional look  
> wouldn't hurt either).

I agree. I'd add that function comments would be a useful thing as  
well. It would be great to be able to call from within the psql  
interpreter a nice concise usage example or explanation. Kind of like  
docstrings in python.

I'd be happy to work on this little piece if anyone has suggestions  
about the best approach.

For my own PostgreSQL usage I have wrapper functions that query the  
function comments (these do exist for most standard PostgreSQL  
functions), and build boilerplate usage text.

I will paste them below if any of you have comments on how to better  
adapt them to PostGIS.


Cheers,

Dane





-- Helper function to find basic info about PostGIS functions
DROP function postgis_help(text);
CREATE or REPLACE function postgis_help(in text, out usage text, out  
comments text)
RETURNS SETOF record AS $$
SELECT  DISTINCT proname||'('||oidvectortypes(proargtypes)||')' as  
usage, obj_description(oid,'pg_proc') as comments FROM pg_proc WHERE  
proname ilike '%' || $1 || '%';
$$ language SQL;
COMMENT on function postgis_help(in text) is $$A function to find the  
usage of other functions. Hint: for all postgis functions that operate  
on WKT type "select * from postgis_help('wkt');"$$;

--// Usage // --
--All WKT functions
select * from postgis_help('wkt')
--All postgis functions
select * from postgis_help(E'st\\_' )
--The query its own comment
select * from postgis_help('help');

-- Helper function to format PostGIS function info into more readable  
strings
DROP function postgis_details(text);
CREATE or REPLACE function postgis_details(in text, out function text,  
out details text, out comments text)
RETURNS SETOF record AS $$
SELECT CASE
	WHEN proname = 'st_affine' and pronargs = 7 then 'st_affine(geometry,  
6 floats)'
	WHEN proname = 'st_affine' and pronargs = 13 then  
'st_affine(geometry, 12 floats)'
	WHEN proname = 'affine' and pronargs = 7 then 'affine(geometry, 6  
floats)'
	WHEN proname = 'affine' and pronargs = 13 then 'affine(geometry, 12  
floats)'
	ELSE replace((proname||'('||oidvectortypes(proargtypes)||')'),  
'double precision', 'float')
END as function, CASE
	WHEN pronargs < 2 then 'Takes '|| pronargs || ' arg,'
	WHEN pronargs > 1 then 'Takes '|| pronargs || ' args,'
END ||  ' returns ' || CASE WHEN p.proretset THEN 'a set of ' ELSE ''  
END || CASE
	WHEN proisagg = 'true' then 'an aggregate '
	WHEN proisagg = 'false' then ''
END|| CASE
	WHEN proname ilike '%kml%' then 'kml geometry'
	WHEN proname ilike '%svg%' then 'gml geometry'
	WHEN proname ilike '%gml%' then 'svg geometry'
	WHEN proname ilike '%ewkt%' then 'Postgis (3d) Well Known Text'
	WHEN proname ilike '%text%' then 'Well Known Text'
	WHEN pg_catalog.format_type(p.prorettype, NULL) = 'bytea' then  
'binary string (bytea)'
	WHEN pg_catalog.format_type(p.prorettype, NULL) = 'integer' then 'an  
integer'
	ELSE replace((pg_catalog.format_type(p.prorettype, NULL)), 'double  
precision', 'a float')
END as Details,
obj_description(oid,'pg_proc') as comments
FROM pg_proc as p WHERE proname ilike '%' || $1 || '%'  order by  
proname;
$$ language SQL;
COMMENT on function postgis_details(in text) is $$A function to find  
the usage of other functions. Hint: for all postgis functions that  
perform affine operations type "select * from  
postgis_details('affine');"$$;

--// Usage // --
select * from postgis_details('affine');
--All postgis functions
select * from postgis_details(E'st\\_' );
--All WKT functions
select * from postgis_details('wkt')



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20080422/710df9ff/attachment.html>