[postgis-users] Postigis self documenting code?

[Dane Springmeyer]

Regina,

Great ideas. I'll comment inline...

On Jun 21, 2008, at 10:37 AM, Paragon Corporation wrote:

> Dane,
>
> This sounds like a great idea.  I had originally planned putting the
> comments in the lwpostgis.sql file

Well, that seems ideal. I am just not familiar with how lwpostgis.sql  
is generated, so I figured the best way for me to help would be to  
provide a separate insert.

Just as long as inserting comments with functions was done in a way to  
avoid introducing any errors and we could find a slick way to patch  
the lwpostgis.sql from the docbook meta that seems like a good route.

> , but I kind of like the idea of
> separating it out into a separate .sql file.
>

Well, maybe this is the best place to start....

And another benefit is that auxiliary meta could be added at the same  
time in a separate table (see below).

> 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

Interesting. I have considered this to the extent that the script  
parses each <para> tag and I have played around with just pulling out  
the first <para> or concatenating all N <para> tags. I've also begin  
implementing logic to search each <para> tag and pull out  
'Availability','the library used', the 'spec', and any cautionary  
notes (like 'don't use this at home (on a geom collection)', etc. I  
figured that this meta would be better stored in its own table that  
could be queried for detailed function info, but I'm open to ideas of  
what most is useful and feasible.

I had not given thought to the issue of how long the comments might  
be. I've only viewed comments in a psql terminal, so long comment  
strings simply wrap. But I can see that PgAdmin must enforce some max  
length (looks like around 140 char) to maintain the readability within  
the 'properties view'. Do you know if PostgreSQL enforces a max length  
on the comments field?

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

Yes,  the script currently interprets '<' as < so those should look  
right in the comments.  I'm sure there are other gremlins though!

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

Hmmm... now that's an idea.

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

I bet you I know less about doc book format! I'd never heard of it  
before trying to parse it, but I'm slowly getting the idea. :)


Cheers,

Dane





> 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
>
>
>
> _______________________________________________
> postgis-users mailing list
> postgis-users at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-users