common.h: add documentation

common.h

@@ -27,7 +27,6 @@
 
 extern int debug;
 extern struct device *global_dev;
-extern struct ubus_context *global_ctx;
 
 #define debug_print(...)                  \
 	do {                                  \
@@ -35,15 +34,6 @@ extern struct ubus_context *global_ctx;
 			fprintf(stderr, __VA_ARGS__); \
 	} while (0)
 
-#define TAG_CONTENT_SIZE 100
-
-struct write_result
-{
-	char *data;
-	int pos;
-};
-
-
 char *get_ip(char *if_name);
 /**
  * Function: print_to_ubus
@@ -89,6 +79,19 @@ struct json_object *xml_to_json_converter(struct write_result *result);
  * 		false if the string contains any non-digit character.
  */
 int isdigits(const char *str);
+
+/**
+ * Function: validate_puk_format
+ *
+ * Checks whether a given PUK code is of valid format or not.
+ *
+ * Parameters:
+ * 		puk - the string to check for structure validity
+ *
+ * Returns:
+ * 		0 if the string is of valid format.
+ * 		-1 on invalid format.
+ */
 int validate_puk_format(char *puk);
 
 /**
@@ -104,7 +107,54 @@ int validate_puk_format(char *puk);
  * 		-1 on invalid format.
  */
 int validate_pin_format(char *pin);
+
+/**
+ * Function: pin_status
+ *
+ * Provides an error response to be used to print a message if the call fails
+ * due to pin being disabled. Up to the caller whether the print this message or
+ * not (depending on the necessity of pin to be disabled or enabled for the feature).
+ *
+ * Parameters:
+ * 		bb - pointer to the buff.
+ *		dev - the device containing the currently active device.
+ *
+ * Returns:
+ * 		0 if the string is of valid format.
+ * 		-1 on invalid format.
+ */
 int pin_status(struct blob_buf *bb, struct device *dev);
+
+/**
+ * Function: check_response
+ *
+ * Determines whether the dongle API response was successful or not. Requires the
+ * response to be in the format of {"result": "success"} or {"result": "failure"}.
+ *
+ * Parameters:
+ * 		response - the json response to parse for success or failure.
+ *
+ * Returns:
+ * 		0 if the response contained success.
+ * 		-1 if the response contained failure.
+ */
 int check_response(struct json_object *response);
 struct json_object *get_json_string_object_by_key(json_object *json_obj, char *string);
+
+/**
+ * Function: remove_newline
+ *
+ * Replaces the first newline character ('\n') found by a null-terminating byte ('\0').
+ *
+ * Parameters:
+ * 		response - the json response to parse for success or failure.
+ *
+ * Returns:
+ * 		0 if the response contained success.
+ * 		-1 if the response contained failure.
+ *
+ * IMPORTANT NOTE
+ *		Will alter the input string!
+ */
+void remove_newline(char *input);
 #endif