add doxygen documentation to coupling API functions

include/toolkitAPI.h

@@ -148,7 +148,7 @@ typedef enum {
     SM_NODEFLOOD      = 4,  /**< Flooding Rate */
     SM_NODEDEPTH      = 5,  /**< Node Depth */
     SM_NODEHEAD       = 6,  /**< Node Head */
-    SM_LATINFLOW      = 7   /**< Lateral Inflow Rate */
+    SM_LATINFLOW      = 7,   /**< Lateral Inflow Rate */
     SM_COUPINFLOW     = 8   /**< Coupling Inflow Rate */
 } SM_NodeResult;
 
@@ -645,15 +645,89 @@ int DLLEXPORT swmm_setOutfallStage(int index, double stage);
 // Coupling API
 //-------------------------------
 
+/**
+ @brief Set an opening for specified node.
+ @param nodeID The index of a node
+ @param idx    The index of an opening
+ @param oType  The opening's type
+ @param A      The opening's area
+ @param l      The opening's length
+ @param Co     The opening's orifice coefficient
+ @param Cfw    The opening's free weir coefficient
+ @param Csw    The opening's submerged weir coefficient
+ @return Error code
+*/
 int DLLEXPORT swmm_setNodeOpening(int nodeID, int idx, int oType, double A,
                                   double l, double Co, double Cfw, double Csw);
+
+/**
+ @brief Remove an opening from a node.
+ @param nodeID The index of a node
+ @param idx    The index of an opening
+ @return Error code
+*/
 int DLLEXPORT swmm_deleteNodeOpening(int nodeID, int idx);
+
+/**
+ @brief Get a node opening's parameter.
+ @param nodeID The index of a node
+ @param idx    The index of an opening
+ @param Param  The opening's parameter to be retrieved (from enum @ref OpeningParams)
+ @param[out] value The value of the opening's property
+ @return Error code
+*/
 int DLLEXPORT swmm_getNodeOpeningParam(int nodeID, int idx, int Param, double *value);
+
+/**
+ @brief Get a node opening's inflow rate.
+ @param nodeID The index of a node
+ @param idx    The index of an opening
+ @param[out] inflow The inflow rate
+ @return Error code
+*/
 int DLLEXPORT swmm_getNodeOpeningFlow(int nodeID, int idx, double *inflow);
+
+/**
+ @brief Get a node opening's type.
+ @param nodeID The index of a node
+ @param idx    The index of an opening
+ @param[out] type The opening type
+ @return Error code
+*/
 int DLLEXPORT swmm_getNodeOpeningType(int nodeID, int idx, int *type);
+
+/**
+ @brief Get a node opening's coupling type.
+ @param nodeID The index of a node
+ @param idx    The index of an opening
+ @param[out] coupling The opening coupling type (from enum @ref OverlandCouplingType)
+ @return Error code
+*/
 int DLLEXPORT swmm_getOpeningCouplingType(int nodeID, int idx, int *coupling);
+
+/**
+ @brief Get the number of openings in a node.
+ @param nodeID The index of a node
+ @param[out] num The number of openings in the given node.
+ @return Error code
+*/
 int DLLEXPORT swmm_getOpeningsNum(int nodeID, int *num);
+
+/**
+ @brief Get the indices of all the openings in a node.
+ @param nodeID The index of a node
+ @param arr_size The size of the results array (from @ref swmm_getOpeningsNum)
+ @param[out] arr An array of the openings indices
+ @return Error code
+*/
 int DLLEXPORT swmm_getOpeningsIndices(int nodeID, int arr_size, int *arr);
+
+/**
+ @brief Get the coupling status of a node.
+ @param nodeID The index of a node
+ @param[out] iscoupled The coupling status of the node.
+ @return Error code
+*/
 int DLLEXPORT swmm_getNodeIsCoupled(int nodeID, int *iscoupled);
 
 #ifdef __cplusplus

src/toolkitAPI.c

@@ -1422,8 +1422,8 @@ int DLLEXPORT swmm_setNodeOpening(int nodeID, int idx, int oType, double A,
 // Input:   nodeID = Index of desired node
 //          idx    = opening's index
 //          otype  = type of opening (grate, etc). Not used yet
-//          A      = area of the opening (ft2)
-//          l      = length of the opening (~circumference, ft)
+//          A      = area of the opening
+//          l      = length of the opening (~circumference)
 //          Co     = orifice coefficient
 //          Cfw    = free weir coefficient
 //          Csw    = submerged weir coefficient
@@ -1451,8 +1451,8 @@ int DLLEXPORT swmm_deleteNodeOpening(int nodeID, int idx)
 //
 // Input:   nodeID = Index of desired node
 //          idx    = opening's index
-// Return:  API Error
-// Purpose: Sets Node opening parameters.
+// Return:  Error code
+// Purpose: Remove an opening from a node.
 {
     // Check if Open
     if(swmm_IsOpenFlag() == FALSE) return(ERR_API_INPUTNOTOPEN);