Add some documentation to the public functions.

git-svn-id: http://svn.osgeo.org/postgis/trunk@5367 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/liblwgeom/lwout_wkb.c b/liblwgeom/lwout_wkb.c
index d89d665011d490b11e09bd534d8a4d173ebabdf4..a926b9a08d1be86263ab006e6cd84221539038cb 100644 (file)
--- a/liblwgeom/lwout_wkb.c
+++ b/liblwgeom/lwout_wkb.c
@@ -297,8 +297,14 @@ static char* ptarray_to_wkb_buf(const POINTARRAY *pa, char *buf, uchar variant)
        int i, j;
        double *dbl_ptr;
        
+       /* Nothing to do with a pointarray with no ordinates */
        if( pa->npoints < 1 )
+       {
+               lwerror("Point array has < 1 ordinates!");
                return buf;
+       }
+               
+       /* SFSQL is always 2-d. Extended and ISO use all available dimensions */
        if( (variant & WKB_ISO) || (variant & WKB_EXTENDED) )
                dims = TYPE_NDIMS(pa->dims);
 
@@ -579,11 +585,12 @@ static char* lwgeom_to_wkb_buf(const LWGEOM *geom, char *buf, uchar variant)
 * Convert LWGEOM to a char* in WKB format. Caller is responsible for freeing
 * the returned array.
 *
-* Accepts variants:
-* One of: WKB_ISO, WKB_EXTENDED, WKB_SFSQL
-* Any of: WKB_NDR
-* For example, a variant = ( WKT_ISO | WKT_NDR ) would return the little-endian 
-* ISO form of WKB.
+* @param variant. Unsigned bitmask value. Accepts one of: WKB_ISO, WKB_EXTENDED, WKB_SFSQL. 
+* Accepts any of: WKB_NDR, WKB_HEX. For example: Variant = ( WKB_ISO | WKB_NDR ) would 
+* return the little-endian ISO form of WKB. For Example: Variant = ( WKB_EXTENDED | WKB_HEX ) 
+* would return the big-endian extended form of WKB, as hex-encoded ASCII (the "canonical form"). 
+* @param size_out If supplied, will return the size of the returned memory segment, 
+* including the null terminator in the case of ASCII.
 */
 char* lwgeom_to_wkb(const LWGEOM *geom, uchar variant, size_t *size_out)
 {
@@ -649,6 +656,9 @@ char* lwgeom_to_wkb(const LWGEOM *geom, uchar variant, size_t *size_out)
                lwfree(wkb_out);
                return NULL;
        }
+
+       /* Report output size */
+       if( size_out ) *size_out = buf_size;
        
        return wkb_out;
 }

diff --git a/liblwgeom/lwout_wkt.c b/liblwgeom/lwout_wkt.c
index 68c57d6a86be392e795629f9d7c86ec2bbf09b66..72c9bd77b52e1041a3bc1c56e540fdbac461203f 100644 (file)
--- a/liblwgeom/lwout_wkt.c
+++ b/liblwgeom/lwout_wkt.c
@@ -526,8 +526,10 @@ static void lwgeom_to_wkt_sb(const LWGEOM *geom, stringbuffer_t *sb, int precisi
 * representation. If size_out is not NULL, it will be set to the size of the
 * allocated *char.
 * 
-* Accepts variants:
-* One of: WKT_ISO, WKT_SFSQL, WKT_EXTENDED
+* @param variant Bitmasked value, accepts one of WKT_ISO, WKT_SFSQL, WKT_EXTENDED.
+* @param precision Number of significant digits in the output doubles.
+* @param size_out If supplied, will return the size of the returned string, 
+* including the null terminator.
 */
 char* lwgeom_to_wkt(const LWGEOM *geom, uchar variant, int precision, size_t *size_out)
 {