From: Regina Obe <lr@pcorp.us>
Date: Mon, 6 Jul 2009 07:33:17 +0000 (+0000)
Subject: Update style on commenting required to be picked up by doxygen
X-Git-Tag: 1.5.0b1~597
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3a3fb33b7e1683c8670b7a214f48f22138c48915;p=postgis

Update style on commenting required to be picked up by doxygen

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

diff --git a/STYLE b/STYLE
index 48a3af45d..c25807d20 100644
--- a/STYLE
+++ b/STYLE
@@ -3,11 +3,11 @@ Coding Style Guidelines for PostGIS
 
 :Preamble:
 
-PostGIS was created over many years, by many different people, some in a 
-hurry. As a result, the existing coding style is all over the map. We 
+PostGIS was created over many years, by many different people, some in a
+hurry. As a result, the existing coding style is all over the map. We
 recognize this, and understand it will be the work of many years before
-PostGIS has a consistently named internal set of functions, but, 
-we can dream. 
+PostGIS has a consistently named internal set of functions, but,
+we can dream.
 
 If new functions follow this guideline, if we do a little rennovation work
 from time to time, we will eventually get there.
@@ -15,7 +15,7 @@ from time to time, we will eventually get there.
 
 :Formatting:
 
-All C code should use an ANSI standard formatting with tabs for block 
+All C code should use an ANSI standard formatting with tabs for block
 indenting. When not block indenting, use spaces. To convert a file
 to the standard format use:
 
@@ -34,10 +34,35 @@ are working on:
 The idea is to avoid combining style-only commits and commits that change
 logic, so the logic commits are easier to read.
 
-Macros should be ALL_UPPERCASE. 
+Macros should be ALL_UPPERCASE.
 Enumerations should be ALL_UPPERCASE.
 
 Comments should be written in C style (/* .... */) and not C++ style (//)
+When describing a function,  the description should be right above the function and should start with /**
+This is so the function description can be picked up by the doxygen autodocumentor.  For example
+
+/**
+** funny_function()
+**
+** Does something funny
+*/
+double funny_function(POINT2D *p1, POINT2D *p2, POINT2D *q){
+	funny stuff here;
+}
+
+More advanced commenting
+/**
+ * Does something funny
+ *
+ * @param p1       : first point
+ * @param p2     : second point
+ * @param q   : the quiet point
+ *
+ * @return a funny double number
+ */
+double funny_function(POINT2D *p1, POINT2D *p2, POINT2D *q){
+	funny stuff here;
+}
 
 
 :Naming:
@@ -52,7 +77,7 @@ For ./liblwgeom:
 
 For ./postgis:
 
-- C functions called by the back-end directly (function(PG_FUNCTION_ARGS)) 
+- C functions called by the back-end directly (function(PG_FUNCTION_ARGS))
   should be named to match their most likely SQL alias. So
   the SQL ST_Distance(geometry) maps to the C function
   ST_Distance(PG_FUNCTION_ARG)