[postgis-users] Postigis self documenting code?

[Paragon Corporation]

Dane,

This sounds like a great idea.  I had originally planned putting the
comments in the lwpostgis.sql file, but I kind of like the idea of
separating it out into a separate .sql file.

The only thing I'm concerned about (which maybe you have already considered
in your python script).  Normally one may want the comments in the docs to
be longer than appears in the postgresql meta data and  sometimes the
postgis xml would have html like code snippets or html entities e.g <
instead of < that would look silly in the postgresql meta data.

I was thinking it might be a good idea to put a special tag around things in
the postgis.xml that we would want included in the meta data and then parse
those tags.

I don't know much about doc book format - are we allowed to extend the dtd
or use existing items in it to accommodate?

Thanks,
Regina 

-----Original Message-----
From: postgis-users-bounces at postgis.refractions.net
[mailto:postgis-users-bounces at postgis.refractions.net] On Behalf Of Dane
Springmeyer
Sent: Saturday, June 21, 2008 12:18 PM
To: PostGIS Users Discussion
Subject: Re: [postgis-users] Postigis self documenting code?

Stanley,

A few weeks ago I placed an issue on the bug tracker that addresses your
'Issue 2'  and I'd love to have feedback since I would be willing to tackle
getting docbook (postgis.xml) meta into db comments however it makes most
sense to do so.

I've written a python script that parses the xml into a sql insert
statement. My thinking is that this calls for a script since we'd want to be
able to update the comments automatically whenever the docbook changes.

http://code.google.com/p/postgis/issues/detail?id=35

Thanks,

Dane


On Jun 20, 2008, at 10:02 AM, Paul Ramsey wrote:

> Please file in the issue tracker.
>
> Even better, submit a patch: this isn't something that takes anything 
> other than a text editor and the will to be great.
>
> P.
>
> On Fri, Jun 20, 2008 at 5:59 PM, Sufficool, Stanley 
> <ssufficool at rov.sbcounty.gov> wrote:
>> Issue 1: Can we just name the arguments to the functions rather that 
>> using aliases? Is this functionality specific to any version of 
>> Postgres? This would give immediate view of args in pgAdmin rather 
>> than scrolling through the code to find the aliases and relating them 
>> to the types in the function definition.
>>
>> ------------------------
>>
>> CREATE OR REPLACE FUNCTION addgeometrycolumn (
>>       catalog_name character varying,
>>       schema_name character varying,
>>       table_name character varying,
>>       column_name character varying,
>>       new_srid integer,
>>       new_type character varying,
>>       new_dim integer
>> )
>> ...
>>
>> ----
>>
>>
>> Issue 2: As mentioned before, can we take the Postgis documentation 
>> of functions and integrate with metadata as follows?
>> ------------------------------
>> COMMENT ON FUNCTION addgeometrycolumn(character varying, character 
>> varying, character varying, character varying, integer, character 
>> varying, integer) IS 'Adds a geometry column to an existing table of 
>> attributes. The schema_name is the name of the table schema (unused 
>> for pre-schema PostgreSQL installations).
>> The srid must be an integer value reference to an entry in the 
>> SPATIAL_REF_SYS table. The type must be an uppercase string 
>> corresponding to the geometry type, eg, 'POLYGON' or 
>> 'MULTILINESTRING'.';
>>
>>
>>
>>
>> _______________________________________________
>> postgis-users mailing list
>> postgis-users at postgis.refractions.net
>> http://postgis.refractions.net/mailman/listinfo/postgis-users
>>
> _______________________________________________
> postgis-users mailing list
> postgis-users at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-users

_______________________________________________
postgis-users mailing list
postgis-users at postgis.refractions.net
http://postgis.refractions.net/mailman/listinfo/postgis-users