Documented the function pointer templates for object_functions, as used in device.c

bacnet-stack/demo/object/device.c

@@ -23,6 +23,9 @@
 *
 *********************************************************************/
 
+/** @file device.c Base "class" for handling all BACnet objects belonging
+ *                 to a BACnet device, as well as Device-specific properties. */
+
 #include <stdbool.h>
 #include <stdint.h>
 #include <string.h>     /* for memmove */

bacnet-stack/include/device.h

@@ -31,6 +31,10 @@
  License.
  -------------------------------------------
 ####COPYRIGHTEND####*/
+
+/** @file device.h Defines functions for handling all BACnet objects belonging
+ *                 to a BACnet device, as well as Device-specific properties. */
+
 #ifndef DEVICE_H
 #define DEVICE_H
 
@@ -44,21 +48,43 @@
 #include "rpm.h"
 #include "readrange.h"
 
+/** Called so a BACnet object can perform any necessary initialization. */
 typedef void (
     *object_init_function) (
     void);
+
+/** Counts the number of objects of this type.
+ * @return Count of implemented objects of this type.
+ */
 typedef unsigned (
     *object_count_function) (
     void);
+
+/** Maps an object index position to its corresponding BACnet object instance number.
+ * @param index [in] The index of the object, in the array of objects of its type.
+ * @return The BACnet object instance number to be used in a BACNET_OBJECT_ID.
+ */
 typedef uint32_t(
     *object_index_to_instance_function)
         (
     unsigned index);
+
+/** Provides the BACnet Object_Name for a given object instance of this type.
+ * @param [in] The object instance number to be looked up.
+ * @return Pointer to a string containing the unique Object_Name.  This string
+ *         is temporary and should be copied upon the return.  It is
+ *         allocated by the system and does not need to be freed.
+ */
 typedef char *(
     *object_name_function)
      (
     uint32_t object_instance);
 
+/** Look in the table of objects of this type, and see if this is a valid
+ *  instance number.
+ * @param [in] The object instance number to be looked up.
+ * @return True if the object instance refers to a valid object of this type.
+ */
 typedef bool(
     *object_valid_instance_function) (
     uint32_t object_instance);

bacnet-stack/include/readrange.h

@@ -124,8 +124,11 @@ typedef struct rrpropertyinfo {
     rr_handler_function Handler;
     } RR_PROP_INFO;
 
-/** Function pointer for ReadRange information retrieval function */
-
+/** Function template for ReadRange information retrieval function.
+ * @param pRequest [in]	Info on the request.
+ * @param pInfo [out]   Where to write the response to.
+ * @return True on success, False on error or failure.
+ */
 typedef bool (*rr_info_function) (
     BACNET_READ_RANGE_DATA *pRequest, /* Info on the request */
     RR_PROP_INFO *pInfo);         /* Where to write the response to */

bacnet-stack/include/rp.h

@@ -50,6 +50,14 @@ typedef struct BACnet_Read_Property_Data {
     BACNET_ERROR_CODE error_code;
 } BACNET_READ_PROPERTY_DATA;
 
+/** Reads one property for this object type of a given instance.
+ * A function template; @see device.c for assignment to object types.
+ *
+ * @param rp_data [in] Pointer to the BACnet_Read_Property_Data structure,
+ *                     which is packed with the information from the RP request.
+ * @return The length of the apdu encoded or -1 for error or
+ *         -2 for abort message.
+ */
 typedef int (
     *read_property_function) (
     BACNET_READ_PROPERTY_DATA *rp_data);

bacnet-stack/include/rpm.h

@@ -49,6 +49,15 @@ typedef struct BACnet_Read_Access_Data {
     struct BACnet_Read_Access_Data *next;
 } BACNET_READ_ACCESS_DATA;
 
+/** Fetches the lists of properties (array of BACNET_PROPERTY_ID's) for this
+ *  object type, grouped by Required, Optional, and Proprietary.
+ * A function template; @see device.c for assignment to object types.
+ *
+ * @param pRequired [out] Pointer reference for the list of Required properties.
+ * @param pOptional [out] Pointer reference for the list of Optional properties.
+ * @param pProprietary [out] Pointer reference for the list of Proprietary
+ *                           properties for this BACNET_OBJECT_TYPE.
+ */
 typedef void (
     *rpm_property_lists_function) (
     const int **pRequired,

bacnet-stack/include/wp.h

@@ -55,6 +55,15 @@ typedef struct BACnet_Write_Property_Data {
     BACNET_ERROR_CODE error_code;
 } BACNET_WRITE_PROPERTY_DATA;
 
+/** Attempts to write a new value to one property for this object type
+ *  of a given instance.
+ * A function template; @see device.c for assignment to object types.
+ *
+ * @param wp_data [in] Pointer to the BACnet_Write_Property_Data structure,
+ *                     which is packed with the information from the WP request.
+ * @return The length of the apdu encoded or -1 for error or
+ *         -2 for abort message.
+ */
 typedef bool(
     *write_property_function) (
     BACNET_WRITE_PROPERTY_DATA * wp_data);