[postgis-users] Postigis self documenting code?

[Kevin Neufeld]

I also really like the idea of having comments on functions and sourcing 
these comments in postgis.xml. 

It seems it would be ideal if, for every function, we had a short 
description, a longer more verbose description, and an example section.  
This way, as Regina suggests, we could have our special tags around the 
short abstracts and extract those into db comments, or a nice function 
overview / quick lookup in the regular documentation.

PaulR, do you know if DocBook can do this? 

-- Kevin

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