[mapserver-commits] r8678 - trunk/docs/development/rfc

[svn at osgeo.org]

Author: dmorissette
Date: 2009-03-08 16:43:31 -0400 (Sun, 08 Mar 2009)
New Revision: 8678

Added:
   trunk/docs/development/rfc/ms-rfc-53.txt
Modified:
   trunk/docs/development/rfc/index.txt
Log:
Added RFC 53: Guidelines for MapScript method return values

Modified: trunk/docs/development/rfc/index.txt
===================================================================
--- trunk/docs/development/rfc/index.txt	2009-03-08 20:32:04 UTC (rev 8677)
+++ trunk/docs/development/rfc/index.txt	2009-03-08 20:43:31 UTC (rev 8678)
@@ -62,4 +62,5 @@
    ms-rfc-50
    ms-rfc-51
    ms-rfc-52
+   ms-rfc-53
 

Added: trunk/docs/development/rfc/ms-rfc-53.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-53.txt	                        (rev 0)
+++ trunk/docs/development/rfc/ms-rfc-53.txt	2009-03-08 20:43:31 UTC (rev 8678)
@@ -0,0 +1,65 @@
+MS RFC 53: Guidelines for MapScript method return values
+======================================================================
+
+:Date: 2009/03/08
+:Authors: Daniel Morissette
+:Contact: dmorissette at mapgears.com
+:Last Edited: 2009/03/08
+:Status: Draft
+:Version: MapServer 6.0
+:Id: $Id: $
+
+Overview
+------------------------------------------------------------------------------
+
+Ticket #244 pointed out that the return values of MapScript methods were
+not consistent: some methods return 0/-1 for success/failure and others
+return MS_SUCCESS/MS_FAILURE.
+
+This mini-RFC defines guidelines for the return values to use with
+MapScript methods in the future.
+
+Technical Solution
+------------------------------------------------------------------------------
+
+Existing methods will remain untouched to avoid breaking existing MapScript 
+applications.
+
+For new methods added to the MapScript API in the future, the following
+guidelines should apply:
+
+1. Return values:
+
+ * If the method returns only a success/failure status then the
+   MS_SUCCESS/MS_FAILURE values should be used.
+ * If the method returns a reference to an object, then it should return a 
+   valid object on success, or a NULL value on failure
+ * If the method returns an positive integer, then it should return a positive 
+   integer on success and -1 on failure. This is a flexible rule which may not 
+   apply in some contexts.
+
+2. Error reporting:
+
+ In case of errors/failures, MapScript developers should ensure that the 
+ MapScript application code can expect to find an errorObj in the error stack.
+ In most cases the core function that MapScript maps to should take care 
+ of calling msSetError(), but in some cases the error may be caught by the 
+ wrapper code and then the wrapper code may be responsible for calling 
+ msSetError() on failure to ensure that the caller has valid error information.
+
+
+Backwards Compatability Issues
+------------------------------------------------------------------------------
+
+None. These guidelines apply only to new MapScript methods. The existing 
+MapScript API remains untouched.
+
+Ticket Id
+------------------------------------------------------------------------------
+
+http://trac.osgeo.org/mapserver/ticket/244
+
+Voting History
+------------------------------------------------------------------------------
+
+No vote yet.