Comments

3 files changed, 24 insertions, 15 deletions

diff --git a/map.h b/map.h
index 43335fb..62b8cee 100644
--- a/map.h
+++ b/map.h
@@ -16,24 +16,22 @@ extern char message[MESSAGE_MAX_SIZE];
 /* Returns an empty map of given size */
 Map empty_map(size_t width, size_t height);
 
-/* Stores all the existing 4dir neighbours of pos in neighbour_array and returns their amount */
+/* Neighbour finding funcs. Find unvisited neighbours of pos in a map of given width and height.
+ * These all store positions of these neighbours into neighbour_array, their costs into cost_array.
+ * Return the amount of neighbours <= amount of dirs */
 unsigned int neighbours_4dir(Position neighbour_array[4], size_t cost_array[4], Position pos, size_t width, size_t height, \
         char **visited, size_t **costs);
-/* Same as above, but walls wrap around. IMPORTANT: the heuristic is tuned to no wraparound, so only dijkstras will work correctly */
 unsigned int neighbours_4dir_wraparound(Position neighbour_array[4], size_t cost_array[4], Position pos, size_t width, size_t height, \
         char **visited, size_t **costs);
-/* Stores all the existing 8dir neighbours of pos in neighbour_array and returns their amount.
- * Additionaly stores costs into cost_array if it's not NULL.
- * The cost of goint orthogonally is 10, diagonaly is 14 (sqrt(2) * 10) */
 unsigned int neighbours_8dir(Position neighbour_array[8], size_t cost_array[8], Position pos, size_t width, size_t height, \
         char **visited, size_t **costs);
-/* Same as above, but walls wrap around. IMPORTANT: the heuristic is tuned to no wraparound, so only dijkstras will work correctly */
 unsigned int neighbours_8dir_wraparound(Position neighbour_array[8], size_t cost_array[8], Position pos, size_t width, size_t height, \
         char **visited, size_t **costs);
 
-/* https://en.wikipedia.org/wiki/Maze_generation_algorithm#Randomized_depth-first_search
- * WARNING: width and height are not the width and height of the returned map!
- * The actual size for a given dimention is (dimension * 2 - 1) */
+/* Generate a maze using the Recursive-Backtracker algorithm, see the link below
+ * https://en.wikipedia.org/wiki/Maze_generation_algorithm#Randomized_depth-first_search
+ * WARNING: width and height are not the width and height of the returned map.
+ *  The actual size for a given dimention is (dimension * 2 - 1) */
 Map rbt_maze_map(size_t width, size_t height, unsigned int seed);
 
 /* Reads the map from a file, saves size in `width` and `height`
@@ -51,10 +49,13 @@ Map rbt_maze_map(size_t width, size_t height, unsigned int seed);
  * ....#.#...
  * ..@....... */
 Map file_plaintext_map(char *filename, size_t *width, size_t *height, Position *start_pos, Position *end_pos);
+
 /* The reverse of above */
 void map_to_file_plaintext(char *filename, Map map, size_t width, size_t height, Position start, Position end);
+
 /* Loads integer costs from a file. Sizes have to match.
- * File format:
+ *
+ * File example:
  * 5x4
  * 10 20 30 40 5
  * 20 49 5 3 2
@@ -66,15 +67,19 @@ size_t **file_plaintext_costs(char *filename, size_t width, size_t height);
  * path could be NULL to draw a map with no path. So can cursor, frontier and visited and cell_costs */
 void draw_map(Map map, size_t **cell_costs, size_t width, size_t height, Position start, Position goal, Position *cursor, Path path, char **visited, PositionPQ *frontier);
 
+/* Has to be called after set_message() to actually display the message. It's called at the end of draw_map() */
 void print_message(size_t height);
 
 /* Frees all the memory reserved for the map */
 void map_free(Map map, size_t height);
 
+/* Was used for debugging, prints the map out to stdout */
 void print_map_out(Map map, size_t width, size_t height);
 
+/* An interactive map editor */
 void map_editor(Map *map, size_t *width, size_t *height, Position *start, Position *goal, int dirs);
 
+/* Copies the map from src to dest */
 void map_copy(Map src, size_t src_w, size_t src_h, Map dest, size_t dest_w, size_t dest_h);
 
 #endif /*MAP_H_ */
diff --git a/path.h b/path.h
index f4f21e8..3b9672d 100644
--- a/path.h
+++ b/path.h
@@ -10,7 +10,7 @@ extern char *path_func_string;
 /* Time it took to calculate a path */
 extern double path_time;
 
-/* Controls whether walls should wrap around, only works in Dijkstra's */
+/* Controls whether walls should wrap around, only works in Dijkstra's due to A*'s heuristic */
 extern char wraparound_enabled;
 
 /* dirs can be 4 or 8 to disallow or allow diagonal movement */
@@ -18,8 +18,10 @@ extern char wraparound_enabled;
 Path dijkstra_path(int dirs, Map map, size_t **cell_costs, size_t width, size_t height, Position start, Position end, char **visited, char should_anim);
 Path astar_path(int dirs, Map map, size_t **cell_costs, size_t width, size_t height, Position start, Position end, char **visited, char should_anim);
 
-size_t manhattan_distance(Position a, Position b);
-size_t diagonal_distance(Position a, Position b);
+/* Heuristic functions. Calculate the distance from a to b */
+size_t manhattan_distance(Position a, Position b); /* Used for 4 dirs */
+size_t diagonal_distance(Position a, Position b);  /* Used for 8 dirs */
+
 
 Path path_new(size_t width, size_t height);
 void path_free(Path path, size_t height);
diff --git a/priority_queue.h b/priority_queue.h
index 8ad4a26..0811205 100644
--- a/priority_queue.h
+++ b/priority_queue.h
@@ -17,18 +17,20 @@ PositionPQ *ppq_new(Position pos, size_t priority);
 
 /* Insert a pos with priority into a given PositionPQ */
 #define PPQ_INSERT_SUCCESS 0
-#define PPQ_INSERT_NEW 1 /* ppq was NULL, created a new one */
+#define PPQ_INSERT_NEW 1     /* ppq was NULL, created a new one */
 #define PPQ_INSERT_ALREADY 2 /* pos is already in ppq */
 int ppq_insert(PositionPQ **ppq, Position pos, size_t priority);
 
 /* Remove and return the position with the lowest priority */
 Position ppq_pop(PositionPQ **ppq);
 
-/* Remove a given pos fron ppq */
+/* Remove a given pos fron ppq, used in ppq_insert() to avoid dups */
 void ppq_remove(PositionPQ **ppq, Position pos);
 
+/* Debug function, prints the contents of ppq to stdout */
 void ppq_print(PositionPQ *ppq);
 
+/* Frees the memory allocated for ppq */
 void ppq_free(PositionPQ *ppq);
 
 #endif /* PRIORITY_QUEUE_H_ */