Tweaked the comments for better Doxygen output.

2010-10-13 19:00:57 +00:00
parent 48411b8dbf
commit a5f24fa19f
8 changed files with 53 additions and 12 deletions
@@ -31,7 +31,7 @@ PROJECT_NAME = BAC-stack
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.

-PROJECT_NUMBER = 1.0
+PROJECT_NUMBER = 0.5.8

 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
@@ -506,7 +506,7 @@ WARN_LOGFILE =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.

-INPUT = include src ports/linux demo/handler demo/object demo/server demo/epics 
+INPUT = include src ports/linux demo/handler demo/object demo/server demo/epics demo/gateway

 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -741,7 +741,7 @@ HTML_ALIGN_MEMBERS = YES
 # Microsoft HTML help workshop to generate a compiled HTML help file (.chm) 
 # of the generated HTML documentation.

-GENERATE_HTMLHELP = NO
+GENERATE_HTMLHELP = YES

 # If the GENERATE_DOCSET tag is set to YES, additional index files 
 # will be generated that can be used as input for Apple's Xcode 3 
@@ -825,7 +825,7 @@ ENUM_VALUES_PER_LINE = 4
 # Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are 
 # probably better off using the HTML help feature.

-GENERATE_TREEVIEW = YES
+GENERATE_TREEVIEW = NO

 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be 
 # used to set the initial width (in pixels) of the frame in which the tree 
@@ -297,8 +297,8 @@ static void Init_Service_Handlers(
 * We also limit the output to 4 bit fields per line.
 *
 * @param stream [in] Normally stdout
- * @param value [in] The structure holding this property's value (union) and type.
- * @param property [in] Which property we are printing.
+ * @param object_value [in] The structure holding this property's description
+ *                          and value.
 * @return True if success.  Or otherwise.
 */

@@ -375,6 +375,8 @@ bool PrettyPrintPropertyValue(
 * through a list (Using_Walked_List is True) to show just one value of the
 * array per call.
 *
+ * @param object_type [in] The BACnet Object type of this object.
+ * @param object_instance [in] The ID number for this object.
 * @param rpm_property [in] Points to structure holding the Property,
 *                          Value, and Error information.
 */
@@ -46,6 +46,7 @@
 *  and passing the remaining bytes to the apdu_handler.
 *  @note The routing (except src) and NCPI information, including 
 *  npdu_data->data_expecting_reply, are discarded.
+ * @ingroup MISCHNDLR
 *  
 * @param src  [out] Returned with routing source information if the NPDU 
 *                   has any and if this points to non-null storage for it. 
@@ -231,11 +231,13 @@ static void routed_apdu_handler(
 *  - Decoding of the NCPI byte
 *  - Further processing by network_control_handler() if this is a  network 
 *    layer message.
- *  - Further processing if it contains an APDU
+ *  - Further processing by routed_apdu_handler() if it contains an APDU
 *    - Normally (no routing) by apdu_handler()
- *    - With Routing (a further destination was indicated) by 
+ *    - With Routing (a further destination was indicated) by the decoded
+ *      destination.
 *  - Errors in decoding.
- *  @note The npdu_data->data_expecting_reply status is discarded.
+ * @note The npdu_data->data_expecting_reply status is discarded.
+ * @ingroup NMRC
 *  
 * @param src  [out] Returned with routing source information if the NPDU 
 *                   has any and if this points to non-null storage for it. 
@@ -229,6 +229,7 @@ int Send_Network_Layer_Message(

 /** Finds a specific router, or all reachable BACnet networks.
 * The response(s) will come in I-am-router-to-network message(s).
+ * @ingroup NMRC
 * 
 * @param dst [in] If NULL, request will be broadcast to the local BACnet
 *                 network.  Optionally may designate a particular router
@@ -249,6 +250,8 @@ void Send_Who_Is_Router_To_Network(
 * we can reach.
 * The message will be sent to our normal DataLink Layer interface, 
 * not the routed backend.
+ * @ingroup NMRC
+ * 
 * @param DNET_list [in] List of BACnet network numbers for which I am a router, 
 *                       terminated with -1
 */
@@ -262,6 +265,7 @@ void Send_I_Am_Router_To_Network(

 /** Finds a specific router, or all reachable BACnet networks.
 * The response(s) will come in I-am-router-to-network message(s).
+ * @ingroup NMRC
 * 
 * @param dst [in] If NULL, request will be broadcast to the local BACnet
 *                 network.  Otherwise, designates a particular router
@@ -290,6 +294,7 @@ void Send_Reject_Message_To_Network(
 *    In that case, DNET[] should just have one entry of -1 (no routing table 
 *    is sent).
 * 2) We are sending out our Routing Table for some reason (normally bcast it).
+ * @ingroup NMRC
 *    
 * @param dst [in] If NULL, msg will be broadcast to the local BACnet network.
 *                 Optionally may designate a particular router destination, 
@@ -316,6 +321,7 @@ void Send_Initialize_Routing_Table(
 *    routing table, and then we will want to respond to that dst router.  
 *    In that case, DNET[] should just have one entry of -1 (no routing table 
 *    is sent).
+ * @ingroup NMRC
 *    
 * @param dst [in] If NULL, Ack will be broadcast to the local BACnet network.
 *                 Optionally may designate a particular router destination, 
@@ -21,7 +21,7 @@
 *---------------------------------------------------------------------
 */

-/** @file gw_device.c  [Description of this file]. */
+/** @file gw_device.c  Functions that extend the Device object to support routing. */

 #include <stdbool.h>
 #include <stdint.h>
@@ -97,11 +97,16 @@ extern "C" {
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
-/** @defgroup RDMS Remote Device Management Services BIBBs
+/** @defgroup RDMS  Device and Network Management Service BIBBs
 * These device management BIBBs prescribe the BACnet capabilities required 
 * to interoperably perform the device management functions enumerated in 
 * 22.2.1.5 for the BACnet devices defined therein. 
- *//** @defgroup DMDCC Device Management-Device Communication Control (DM-DCC)
+ * 
+ * The network management BIBBs prescribe the BACnet capabilities required to 
+ * interoperably perform network management functions.
+ */
+
+/** @defgroup DMDCC Device Management-Device Communication Control (DM-DCC)
 * @ingroup RDMS
 * 16.1 DeviceCommunicationControl Service <br>
 * The DeviceCommunicationControl service is used by a client BACnet-user to 
@@ -115,4 +120,20 @@ extern "C" {
 * DeviceCommunicationControl or, if supported, ReinitializeDevice service, 
 * not by time.
 */
+
+/** @defgroup NMRC Network Management-Router Configuration (NM-RC)
+ * @ingroup RDMS
+ * The A device may query and change the configuration of routers and 
+ * half-routers.
+ * The B device responds to router management commands and must meet the 
+ * requirements for BACnet Routers as stated in Clause 6.
+ * 
+ * 6.4 Network Layer Protocol Messages <br>
+ * This subclause describes the format and purpose of the ten BACnet network 
+ * layer protocol messages. These messages provide the basis for router 
+ * auto-configuration, router table maintenance, and network layer congestion 
+ * control.
+ */
+
+
 #endif
@@ -357,6 +357,15 @@ void apdu_retries_set(
    Number_Of_Retries = value;
 }

+/** Process the APDU header and invoke the appropriate service handler
+ * to manage the received request.
+ * Almost all requests and ACKs invoke this function.
+ * @ingroup MISCHNDLR
+ * 
+ * @param src [in] The BACNET_ADDRESS of the message's source.
+ * @param apdu [in] The apdu portion of the request, to be processed.
+ * @param apdu_len [in] The total (remaining) length of the apdu.
+ */
 void apdu_handler(
    BACNET_ADDRESS * src,
    uint8_t * apdu,     /* APDU data */