Improved documentation in the code

Signed-off-by: David Sommerseth <davids@redhat.com>

4 files changed, 94 insertions, 25 deletions

diff --git a/python-ethtool/etherinfo.c b/python-ethtool/etherinfo.c
index 68cc2e6..bfbe11d 100644
--- a/python-ethtool/etherinfo.c
+++ b/python-ethtool/etherinfo.c
@@ -35,6 +35,14 @@
  *   Internal functions for working with struct etherinfo
  *
  */
+
+/**
+ * Simple macro which makes sure the destination string is freed if used earlier.
+ *
+ * @param dst Destination pointer
+ * @param src Source pointer
+ *
+ */
 #define SET_STR_VALUE(dst, src) {	 \
 	if( dst ) {		 \
 		free(dst);	 \
@@ -43,6 +51,11 @@
 	}
 
 
+/**
+ * Frees the memory used by a struct ipv6address pointer chain.  All elements are freed
+ *
+ * @param ptr  Pointer to a struct ipv6address chain.
+ */
 void free_ipv6addresses(struct ipv6address *ptr) {
 	struct ipv6address *ipv6ptr = ptr;
 
@@ -59,6 +72,11 @@ void free_ipv6addresses(struct ipv6address *ptr) {
 	}
 }
 
+/**
+ * Frees the memory used by struct etherinfo, including all struct ipv6address children.
+ *
+ * @param ptr Pointer to a struct etherninfo element
+ */
 void free_etherinfo(struct etherinfo *ptr)
 {
 	if( ptr == NULL ) { // Just for safety
@@ -82,6 +100,17 @@ void free_etherinfo(struct etherinfo *ptr)
 	free(ptr);
 }
 
+
+/**
+ * Add a new IPv6 address record to a struct ipv6address chain
+ *
+ * @param addrptr    Pointer to the current IPv6 address chain.
+ * @param addr       IPv6 address, represented as char * string
+ * @param netmask    IPv6 netmask, as returned by libnl rtnl_addr_get_prefixlen()
+ * @param scope      IPV6 address scope, as returned by libnl rtnl_addr_get_scope()
+ *
+ * @return Returns a new pointer to the chain containing the new element
+ */
 struct ipv6address * etherinfo_add_ipv6(struct ipv6address *addrptr, const char *addr, int netmask, int scope) {
 	struct ipv6address *newaddr = NULL;
 
@@ -100,11 +129,13 @@ struct ipv6address * etherinfo_add_ipv6(struct ipv6address *addrptr, const char
 }
 
 
-/*
- *  libnl callback functions
+/**
+ *  libnl callback function.  Does the real parsing of a record returned by NETLINK.  This function
+ *  parses LINK related packets
  *
+ * @param obj   Pointer to a struct nl_object response
+ * @param arg   Pointer to a struct etherinfo element where the parse result will be saved
  */
-
 static void callback_nl_link(struct nl_object *obj, void *arg)
 {
 	struct etherinfo *ethi = (struct etherinfo *) arg;
@@ -137,6 +168,13 @@ static void callback_nl_link(struct nl_object *obj, void *arg)
 }
 
 
+/**
+ *  libnl callback function.  Does the real parsing of a record returned by NETLINK.  This function
+ *  parses ADDRESS related packets
+ *
+ * @param obj   Pointer to a struct nl_object response
+ * @param arg   Pointer to a struct etherinfo element where the parse result will be saved
+ */
 static void callback_nl_address(struct nl_object *obj, void *arg)
 {
 	struct etherinfo *ethi = (struct etherinfo *) arg;
@@ -188,6 +226,12 @@ static void callback_nl_address(struct nl_object *obj, void *arg)
  *
  */
 
+/**
+ * Dumps the contents of a struct etherinfo element to file
+ *
+ * @param fp   FILE pointer where to dump
+ * @param ptr  Pointer to a struct etherinfo element
+ */
 void dump_etherinfo(FILE *fp, struct etherinfo *ptr)
 {
 
@@ -220,6 +264,16 @@ void dump_etherinfo(FILE *fp, struct etherinfo *ptr)
 }
 
 
+/**
+ * Query NETLINK for ethernet configuration
+ *
+ * @param ethinf Pointer to an available struct etherinfo element.  The 'device' member
+ *               must contain a valid string to the device to query for information
+ * @param nlc    Pointer to the libnl handle, which is used for the query against NETLINK
+ * @param query  What to query for.  Must be NLQRY_LINK or NLQRY_ADDR.
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int get_etherinfo(struct etherinfo *ethinf, struct _nlconnection *nlc, nlQuery query)
 {
 	struct nl_cache *link_cache;
diff --git a/python-ethtool/etherinfo.h b/python-ethtool/etherinfo.h
index 0d441a3..7e79d67 100644
--- a/python-ethtool/etherinfo.h
+++ b/python-ethtool/etherinfo.h
@@ -24,7 +24,7 @@
 #include <netlink/route/addr.h>
 #include <arpa/inet.h>
 
-typedef enum {NLQRY_LINK, NLQRY_ADDR} nlQuery;
+typedef enum {NLQRY_LINK, NLQRY_ADDR} nlQuery; /**<  Supported query types in the etherinfo code */
 
 int get_etherinfo(struct etherinfo *ethinf, struct _nlconnection *nlc, nlQuery query);
 void free_etherinfo(struct etherinfo *ptr);
diff --git a/python-ethtool/etherinfo_ipv6_obj.c b/python-ethtool/etherinfo_ipv6_obj.c
index cec5248..b2ac4ba 100644
--- a/python-ethtool/etherinfo_ipv6_obj.c
+++ b/python-ethtool/etherinfo_ipv6_obj.c
@@ -16,7 +16,7 @@
 
 
 /**
- * ethtool.etherinfo deallocator - cleans up when a object is deleted
+ * ethtool.etherinfo_ipv6addr deallocator - cleans up when a object is deleted
  *
  * @param self etherinfo_ipv6_py object structure
  */
@@ -30,7 +30,7 @@ void _ethtool_etherinfo_ipv6_dealloc(etherinfo_ipv6_py *self)
 
 
 /**
- * ethtool.etherinfo function, creating a new etherinfo object
+ * ethtool.etherinfo_ipv6addr function, creating a new etherinfo object
  *
  * @param type
  * @param args
@@ -48,7 +48,7 @@ PyObject *_ethtool_etherinfo_ipv6_new(PyTypeObject *type, PyObject *args, PyObje
 
 
 /**
- * ethtool.etherinfo init (constructor) method.  Makes sure the object is initialised correctly.
+ * ethtool.etherinfo_ipv6addr init (constructor) method.  Makes sure the object is initialised correctly.
  *
  * @param self
  * @param args
@@ -70,7 +70,7 @@ int _ethtool_etherinfo_ipv6_init(etherinfo_ipv6_py *self, PyObject *args, PyObje
 }
 
 /**
- * ethtool.etherinfo function for retrieving data from a Python object.
+ * ethtool.etherinfo_ipv6addr function for retrieving data from a Python object.
  *
  * @param self
  * @param attr_o  contains the object member request (which element to return)
@@ -104,7 +104,7 @@ PyObject *_ethtool_etherinfo_ipv6_getter(etherinfo_ipv6_py *self, PyObject *attr
 
 
 /**
- * ethtool.etherinfo function for setting a value to a object member.  This feature is
+ * ethtool.etherinfo_ipv6addr function for setting a value to a object member.  This feature is
  * disabled by always returning -1, as the values are read-only by the user.
  *
  * @param self
diff --git a/python-ethtool/etherinfo_struct.h b/python-ethtool/etherinfo_struct.h
index 8f9e2e5..22616fb 100644
--- a/python-ethtool/etherinfo_struct.h
+++ b/python-ethtool/etherinfo_struct.h
@@ -10,25 +10,33 @@
 #ifndef _ETHERINFO_STRUCT_H
 #define _ETHERINFO_STRUCT_H
 
-
+/**
+ * Contains IP address information about a particular ethernet device
+ *
+ */
 struct etherinfo {
-	char *device;
-	int index;
-	char *hwaddress;
-	char *ipv4_address;
-	int ipv4_netmask;
-	char *ipv4_broadcast;
-	struct ipv6address *ipv6_addresses;
+	char *device;                       /**< Device name */
+	int index;                          /**< NETLINK index reference */
+	char *hwaddress;                    /**< HW address / MAC address of device */
+	char *ipv4_address;                 /**< Configured IPv4 address */
+	int ipv4_netmask;                   /**< Configured IPv4 netmask */
+	char *ipv4_broadcast;               /**< Configured IPv4 broadcast address */
+	struct ipv6address *ipv6_addresses; /**< Configured IPv6 addresses (as a pointer chain) */
 };
 
+
+/**
+ * Pointer chain with IPv6 addresses associated with a ethernet interface.  Used
+ * by struct etherinfo
+ */
 struct ipv6address {
-	char *address;
-	int netmask;
-	int scope;
-	struct ipv6address *next;
+	char *address;               /**<  Configured IPv6 address */
+	int netmask;                 /**<  Configured IPv6 netmask */
+	int scope;                   /**<  Scope for the IPv6 address */
+	struct ipv6address *next;    /**<  Pointer to next configured IPv6 address */
 };
 
-/*
+/**
  *  NETLINK connection handle and related information to be shared
  *  among all the instantiated etherinfo objects.
  */
@@ -46,15 +54,22 @@ struct etherinfo_obj_data {
 	struct etherinfo *ethinfo;      /**< Contains info about our current interface */
 };
 
+/**
+ * A Python object of struct etherinfo_obj_data
+ *
+ */
 typedef struct {
 	PyObject_HEAD
-	struct etherinfo_obj_data *data;
+	struct etherinfo_obj_data *data; /* IPv4 and IPv6 address information, only one element used */
 } etherinfo_py;
 
-
+/**
+ * A Python object of struct ipv6address
+ *
+ */
 typedef struct {
 	PyObject_HEAD
-	struct ipv6address *addrdata;
+	struct ipv6address *addrdata; /**< IPv6 address, only one element is used in this case */
 } etherinfo_ipv6_py;
 
 /**