<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Apr 21, 2008, at 9:52 PM, Kevin Neufeld wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0; ">These all sound good to me. Can we add to this list a documentation overhaul?<span class="Apple-converted-space"> </span><br>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).<span class="Apple-converted-space"> </span></span></blockquote></div><br><div>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.</div><div><br></div><div>I'd be happy to work on this little piece if anyone has suggestions about the best approach.</div><div><br></div><div>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.</div><div><br></div><div>I will paste them below if any of you have comments on how to better adapt them to PostGIS.</div><div><br></div><div><br></div><div>Cheers,</div><div><br></div><div>Dane</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">-- Helper function to find basic info about PostGIS functions</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">DROP</span> <span style="color: #0000cc">function</span> postgis_help(text);</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">CREATE</span> <span style="color: #0000cc">or</span> REPLACE <span style="color: #0000cc">function</span> postgis_help(<span style="color: #0000cc">in</span> text, <span style="color: #0000cc">out</span> <span style="color: #0000cc">usage</span> text, <span style="color: #0000cc">out</span> comments text)</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">RETURNS</span> SETOF record <span style="color: #0000cc">AS</span> $$</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">SELECT</span> <span style="color: #0000cc">DISTINCT</span> proname||<span style="color: #ff2f51">'('</span>||oidvectortypes(proargtypes)||<span style="color: #ff2f51">')'</span> <span style="color: #0000cc">as</span> <span style="color: #0000cc">usage</span>, obj_description(<span style="color: #0000cc">oid</span>,<span style="color: #ff2f51">'pg_proc'</span>) <span style="color: #0000cc">as</span> comments <span style="color: #0000cc">FROM</span> pg_proc <span style="color: #0000cc">WHERE</span> proname ilike <span style="color: #ff2f51">'%'</span> || $1 || <span style="color: #ff2f51">'%'</span>;</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; ">$$ <span style="color: #0000cc">language</span> SQL;</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; ">COMMENT <span style="color: #0000cc">on</span> <span style="color: #0000cc">function</span> postgis_help(<span style="color: #0000cc">in</span> text) <span style="color: #0000cc">is</span> $$A <span style="color: #0000cc">function</span> <span style="color: #0000cc">to</span> find the <span style="color: #0000cc">usage</span> <span style="color: #0000cc">of</span> other functions. Hint: <span style="color: #0000cc">for</span> <span style="color: #0000cc">all</span> postgis functions that operate <span style="color: #0000cc">on</span> WKT <span style="color: #0000cc">type</span> <span style="color: #336699">"select * from postgis_help('wkt');"</span>$$;</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; min-height: 13px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">--// Usage // --</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">--All WKT functions</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">select</span> * <span style="color: #0000cc">from</span> postgis_help(<span style="color: #ff2f51">'wkt'</span>)</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">--All postgis functions</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">select</span> * <span style="color: #0000cc">from</span> postgis_help(E<span style="color: #ff2f51">'st\\_'</span> )</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">--The query its own comment</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">select</span> * <span style="color: #0000cc">from</span> postgis_help(<span style="color: #ff2f51">'help'</span>);</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; min-height: 13px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">-- Helper function to format PostGIS function info into more readable strings</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">DROP</span> <span style="color: #0000cc">function</span> postgis_details(text);</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">CREATE</span> <span style="color: #0000cc">or</span> REPLACE <span style="color: #0000cc">function</span> postgis_details(<span style="color: #0000cc">in</span> text, <span style="color: #0000cc">out</span> <span style="color: #0000cc">function</span> text, <span style="color: #0000cc">out</span> details text, <span style="color: #0000cc">out</span> comments text)</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">RETURNS</span> SETOF record <span style="color: #0000cc">AS</span> $$</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(0, 0, 204); ">SELECT<span style="color: #000000"> </span>CASE</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname = </span>'st_affine'<span style="color: #000000"> </span><span style="color: #0000cc">and</span><span style="color: #000000"> pronargs = 7 </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'st_affine(geometry, 6 floats)'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname = </span>'st_affine'<span style="color: #000000"> </span><span style="color: #0000cc">and</span><span style="color: #000000"> pronargs = 13 </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'st_affine(geometry, 12 floats)'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname = </span>'affine'<span style="color: #000000"> </span><span style="color: #0000cc">and</span><span style="color: #000000"> pronargs = 7 </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'affine(geometry, 6 floats)'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname = </span>'affine'<span style="color: #000000"> </span><span style="color: #0000cc">and</span><span style="color: #000000"> pronargs = 13 </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'affine(geometry, 12 floats)'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #0000cc">ELSE</span> replace((proname||<span style="color: #ff2f51">'('</span>||oidvectortypes(proargtypes)||<span style="color: #ff2f51">')'</span>), <span style="color: #ff2f51">'double precision'</span>, <span style="color: #ff2f51">'float'</span>)</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(0, 0, 204); ">END<span style="color: #000000"> </span>as<span style="color: #000000"> </span>function<span style="color: #000000">, </span>CASE<span style="color: #000000"> </span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #0000cc">WHEN</span> pronargs < 2 <span style="color: #0000cc">then</span> <span style="color: #ff2f51">'Takes '</span>|| pronargs || <span style="color: #ff2f51">' arg,'</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #0000cc">WHEN</span> pronargs > 1 <span style="color: #0000cc">then</span> <span style="color: #ff2f51">'Takes '</span>|| pronargs || <span style="color: #ff2f51">' args,'</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">END</span> || <span style="color: #ff2f51">' returns '</span> || <span style="color: #0000cc">CASE</span> <span style="color: #0000cc">WHEN</span> p.proretset <span style="color: #0000cc">THEN</span> <span style="color: #ff2f51">'a set of '</span> <span style="color: #0000cc">ELSE</span> <span style="color: #ff2f51">''</span> <span style="color: #0000cc">END</span> || <span style="color: #0000cc">CASE</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proisagg = </span>'true'<span style="color: #000000"> </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'an aggregate '</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #0000cc">WHEN</span> proisagg = <span style="color: #ff2f51">'false'</span> <span style="color: #0000cc">then</span> <span style="color: #ff2f51">''</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(0, 0, 204); ">END<span style="color: #000000">|| </span>CASE</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname ilike </span>'%kml%'<span style="color: #000000"> </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'kml geometry'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname ilike </span>'%svg%'<span style="color: #000000"> </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'gml geometry'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname ilike </span>'%gml%'<span style="color: #000000"> </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'svg geometry'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname ilike </span>'%ewkt%'<span style="color: #000000"> </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'Postgis (3d) Well Known Text'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(255, 47, 81); "><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #0000cc">WHEN</span><span style="color: #000000"> proname ilike </span>'%text%'<span style="color: #000000"> </span><span style="color: #0000cc">then</span><span style="color: #000000"> </span>'Well Known Text'</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #0000cc">WHEN</span> pg_catalog.format_type(p.prorettype, <span style="color: #0000cc">NULL</span>) = <span style="color: #ff2f51">'bytea'</span> <span style="color: #0000cc">then</span> <span style="color: #ff2f51">'binary string (bytea)'</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #0000cc">WHEN</span> pg_catalog.format_type(p.prorettype, <span style="color: #0000cc">NULL</span>) = <span style="color: #ff2f51">'integer'</span> <span style="color: #0000cc">then</span> <span style="color: #ff2f51">'an integer'</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #0000cc">ELSE</span> replace((pg_catalog.format_type(p.prorettype, <span style="color: #0000cc">NULL</span>)), <span style="color: #ff2f51">'double precision'</span>, <span style="color: #ff2f51">'a float'</span>)</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">END</span> <span style="color: #0000cc">as</span> Details,</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; ">obj_description(<span style="color: #0000cc">oid</span>,<span style="color: #ff2f51">'pg_proc'</span>) <span style="color: #0000cc">as</span> comments</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">FROM</span> pg_proc <span style="color: #0000cc">as</span> p <span style="color: #0000cc">WHERE</span> proname ilike <span style="color: #ff2f51">'%'</span> || $1 || <span style="color: #ff2f51">'%'</span> <span style="color: #0000cc">order</span> <span style="color: #0000cc">by</span> proname;</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; ">$$ <span style="color: #0000cc">language</span> SQL;</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; ">COMMENT <span style="color: #0000cc">on</span> <span style="color: #0000cc">function</span> postgis_details(<span style="color: #0000cc">in</span> text) <span style="color: #0000cc">is</span> $$A <span style="color: #0000cc">function</span> <span style="color: #0000cc">to</span> find the <span style="color: #0000cc">usage</span> <span style="color: #0000cc">of</span> other functions. Hint: <span style="color: #0000cc">for</span> <span style="color: #0000cc">all</span> postgis functions that perform affine operations <span style="color: #0000cc">type</span> <span style="color: #336699">"select * from postgis_details('affine');"</span>$$;</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; min-height: 13px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">--// Usage // --</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">select</span> * <span style="color: #0000cc">from</span> postgis_details(<span style="color: #ff2f51">'affine'</span>);</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">--All postgis functions</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">select</span> * <span style="color: #0000cc">from</span> postgis_details(E<span style="color: #ff2f51">'st\\_'</span> );</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; color: rgb(85, 85, 85); ">--All WKT functions</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font: normal normal normal 11px/normal 'Lucida Grande'; "><span style="color: #0000cc">select</span> * <span style="color: #0000cc">from</span> postgis_details(<span style="color: #ff2f51">'wkt'</span>)</div></div><div><br></div><div><br></div><div><br></div></body></html>