From 56872086fa615132a3bdff39af8b38c09cae159f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mario=20H=C3=BCttel?= <mario.huettel@gmx.net>
Date: Sat, 23 Oct 2021 21:14:24 +0200
Subject: [PATCH] Comment code

---
 .../temp-profile/temp-profile-parser.h        |  4 +--
 .../temp-profile/temp-profile-parser.c        | 27 ++++++++++++++++++-
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/stm-firmware/include/reflow-controller/temp-profile/temp-profile-parser.h b/stm-firmware/include/reflow-controller/temp-profile/temp-profile-parser.h
index ed5092e..f05d3c9 100644
--- a/stm-firmware/include/reflow-controller/temp-profile/temp-profile-parser.h
+++ b/stm-firmware/include/reflow-controller/temp-profile/temp-profile-parser.h
@@ -56,7 +56,7 @@ enum pl_ret_val {
 };
 
 /**
- * @brief Maximum parameter count of a command
+ * @brief Maximum parameter count of a command.
  */
 #define PROFILE_LANG_MAX_NUM_ARGS (8)
 
@@ -89,7 +89,7 @@ enum pl_ret_val temp_profile_parse_from_file(const char *filename,
 					     uint32_t *cmds_parsed);
 
 /**
- * @brief Fully free a comamnd list including hte sotred command structures.
+ * @brief Fully free a comamnd list including hte stored command structures.
  *
  * \p list's destination is set to NULL to indicate the empty list.
  *
diff --git a/stm-firmware/temp-profile/temp-profile-parser.c b/stm-firmware/temp-profile/temp-profile-parser.c
index a6c9685..28b9d7a 100644
--- a/stm-firmware/temp-profile/temp-profile-parser.c
+++ b/stm-firmware/temp-profile/temp-profile-parser.c
@@ -108,6 +108,13 @@ static const struct pl_command_list_map *string_to_command(const char *str)
 	return ret;
 }
 
+/**
+ * @brief Parse a line in the temperature profile to a command.
+ * @param line Line to parse
+ * @param[out] cmd Command parsed
+ * @return negative in case of an error (Invalid command, invalid line);
+ * 1 in case the line is an empty line.
+ */
 static int parse_line(char *line, struct pl_command *cmd)
 {
 	uint8_t token_idx = 0;
@@ -123,7 +130,10 @@ static int parse_line(char *line, struct pl_command *cmd)
 	token = strtok(line, delim);
 
 	if (!token) {
-		/* Empty line or command line */
+		/* Empty line.
+		 * Note: The comments in the lines are already filteed out before calling this function.
+		 * Therefore, the empty line case covers lines containing just a comment
+		 */
 		return 1;
 	}
 
@@ -162,12 +172,23 @@ static int parse_line(char *line, struct pl_command *cmd)
 	return 0;
 }
 
+/**
+ * @brief Append a command to a singly linked list.
+ *
+ * The the list item is newly allocated and the command is copied. Therefore, \p cmd can be overwritten after
+ * a call to this function.
+ *
+ * @param list List to add the command to
+ * @param cmd Command to add to list
+ * @return The new head of the list. If an error occured */
 static SlList *copy_and_append_command_to_list(SlList *list, const struct pl_command *cmd)
 {
 	struct pl_command *alloced_cmd;
 
 	alloced_cmd = (struct pl_command *)malloc(sizeof(struct pl_command));
 	memcpy(alloced_cmd, cmd, sizeof(struct pl_command));
+
+	/* This will go catastrophically wrong, if the heap is full... just saying. */
 	list = sl_list_append(list, alloced_cmd);
 
 	return list;
@@ -235,6 +256,10 @@ exit:
 	return ret;
 }
 
+/**
+ * @brief Free an allocated pl_command structure
+ * @param cmd command struct. Tolerates NULL.
+ */
 static void delete_pl_command(void *cmd)
 {
 	if (cmd)