docs: add documentation to each .c.md file

includes/internal/map_internal.h.md

@@ -11,11 +11,5 @@
 int8_t
 map_grow(t_map *map);
 
-int8_t
-write_header(FILE *f, const char *source, const char *target);
-
-int8_t
-write_ranges(FILE *f, t_map *map);
-
 #endif
 ```

includes/internal/transpile_internal.h.md

@@ -23,9 +23,6 @@ typedef struct s_state
 void
 state_init(t_state *s, FILE *in, FILE *out, const char *ext, t_map *map);
 
-int8_t
-process_line(t_state *s, char *line);
-
 int8_t
 handle_fence_open(t_state *s, char *line);
 

srcs/cli/cli.c.md

@@ -1,18 +1,39 @@
+# cli.c
+The command-line interface (CLI) parser for the c-md transpiler.
+Handles parsing command-line arguments and populating the t_args structure.
+
+---
+
+
+### Includes
 ```c
 #include <stddef.h>
 #include <getopt.h>
 #include <string.h>
 
 #include "cli.h"
+```
 
+---
+
+### Structs and Type Definitions
+
+Function pointer type for option handlers.
+```c
 typedef void (*t_handler)(t_args *, const char *);
+```
 
+Struct to map short options to their handlers.
+```c
 typedef struct s_opt
 {
 	int8_t		short_opt;
 	t_handler	handler;
 }	t_opt;
+```
 
+### Forward Declarations
+```c
 static void		handle_help(t_args *args, const char *value);
 static void		handle_ext(t_args *args, const char *value);
 static void		handle_input(t_args *args, const char *value);
@@ -20,7 +41,12 @@ static void		handle_output(t_args *args, const char *value);
 static void		handle_map(t_args *args, const char *value);
 static t_handler	find_handler(int8_t opt);
 static void		init_args(t_args *args);
+```
 
+### Static Variables
+
+Initialize the mapping of options to their handlers.
+```c
 static const t_opt g_opts[] = {
 	{'h', handle_help},
 	{'e', handle_ext},
@@ -29,7 +55,11 @@ static const t_opt g_opts[] = {
 	{'m', handle_map},
 	{0, NULL}
 };
+```
 
+Initialize the long options for getopt_long.
+See `man getopt` for details.
+```c
 static struct option g_long_opts[] = {
 	{"help", no_argument, NULL, 'h'},
 	{"ext", required_argument, NULL, 'e'},
@@ -38,7 +68,23 @@ static struct option g_long_opts[] = {
 	{"map", required_argument, NULL, 'm'},
 	{NULL, 0, NULL, 0}
 };
+```
 
+### Function Definitions
+
+### `cli_parse`
+Parses command-line arguments and populates the t_args structure.
+
+#### Parameters
+- `args`: Pointer to the t_args structure to populate.
+- `argc`: Argument count.
+- `argv`: argv.
+
+#### Return Value
+Returns 0 on success, or -1 on failure.
+
+#### Implementation
+```c
 int8_t
 cli_parse(t_args *args, int32_t argc, char **argv)
 {
@@ -55,7 +101,16 @@ cli_parse(t_args *args, int32_t argc, char **argv)
 	}
 	return (0);
 }
+```
 
+### `init_args`
+Initializes the t_args structure with default values.
+
+#### Parameters
+- `args`: Pointer to the t_args structure to initialize.
+
+#### Implementation
+```c
 static void
 init_args(t_args *args)
 {
@@ -65,7 +120,19 @@ init_args(t_args *args)
 	args->map_path = NULL;
 	args->show_help = 0;
 }
+```
 
+### `find_handler`
+Finds the handler function for a given option.
+
+#### Parameters
+- `opt`: The short option character.
+
+#### Return Value
+Returns the corresponding handler function, or NULL if not found.
+
+#### Implementation
+```c
 static t_handler
 find_handler(int8_t opt)
 {
@@ -80,32 +147,52 @@ find_handler(int8_t opt)
 	}
 	return (NULL);
 }
+```
 
+### `handle_help`
+Sets the show_help flag in t_args.
+```c
 static void
 handle_help(t_args *args, const char *value)
 {
 	(void)value;
 	args->show_help = 1;
 }
+```
 
+### `handle_ext`
+Sets the file extension in t_args.
+```c
 static void
 handle_ext(t_args *args, const char *value)
 {
 	args->ext = value;
 }
+```
 
+### `handle_input`
+Sets the input file path in t_args.
+```c
 static void
 handle_input(t_args *args, const char *value)
 {
 	args->input = value;
 }
+```
 
+### `handle_output`
+Sets the output file path in t_args.
+```c
 static void
 handle_output(t_args *args, const char *value)
 {
 	args->output = value;
 }
+```
 
+### `handle_map`
+Sets the mapping file path in t_args.
+```c
 static void
 handle_map(t_args *args, const char *value)
 {

srcs/cli/help.c.md

@@ -1,8 +1,23 @@
+# help.c
+
+---
+
+## Includes
 ```c
 #include <stdio.h>
 
 #include "cli.h"
+```
 
+## Function Descriptions
+### `cli_print_help`
+Prints the help message for the command-line interface.
+
+#### Parameters
+- `progname`: Name of the program.
+
+#### Implementation
+```c
 void
 cli_print_help(const char *progname)
 {

srcs/io/streams.c.md

@@ -1,8 +1,35 @@
+# streams.c
+Funtions for handling input and output streams.
+
+---
+
+## Includes
 ```c
 #include <stdio.h>
 
 #include "io.h"
+```
 
+---
+
+## Function Descriptions
+
+### `io_open`
+Opens input and output streams based on provided file paths.
+if input_path is NULL, stdin is used.
+if output_path is NULL, stdout is used.
+
+#### Parameters
+- `io`: Pointer to the t_io structure to hold the opened streams.
+- `input_path`: Path to the input file, or NULL for stdin.
+- `output_path`: Path to the output file, or NULL for stdout.
+
+#### Return Value
+Returns 0 on success, or 1 on failure.
+The caller is responsible for closing the streams using `io_close`.
+
+#### Implementation
+```c
 int8_t
 io_open(t_io *io, const char *input_path, const char *output_path)
 {
@@ -22,7 +49,16 @@ io_open(t_io *io, const char *input_path, const char *output_path)
 	}
 	return (0);
 }
+```
 
+### `io_close`
+Closes the input and output streams if they are not stdin or stdout.
+
+#### Parameters
+- `io`: Pointer to the t_io structure containing the streams to close.
+
+#### Implementation
+```c
 void
 io_close(t_io *io)
 {

srcs/main.c.md

@@ -1,3 +1,10 @@
+# main.c
+
+Entry point of the c-md transpiler.
+
+Parse command-line arguments, validate them, and run the transpilation process.
+
+## Includes
 ```c
 #include <stdio.h>
 #include <stdint.h>
@@ -7,10 +14,20 @@
 #include "transpile.h"
 #include "map.h"
 #include "io.h"
+```
 
+## Forward Declarations
+
+```c
 static int8_t	run(t_args *args);
 static void	print_error(int8_t code, const char *progname);
+```
 
+## Main Function
+
+Program entry point: parse arguments, validate, and run transpilation.
+
+```c
 int
 main(int argc, char **argv)
 {
@@ -35,7 +52,17 @@ main(int argc, char **argv)
 	}
 	return (run(&args));
 }
+```
 
+## Print Error Function
+
+print_error: Print error messages based on validation code.
+
+error codes:
+1. Missing -e when reading from stdin
+2. Missing -e when filename does not imply extension
+
+```c
 static void
 print_error(int8_t code, const char *progname)
 {
@@ -45,7 +72,13 @@ print_error(int8_t code, const char *progname)
 		fprintf(stderr, "Error: -e required (cannot infer from filename)\n");
 	cli_print_help(progname);
 }
+```
 
+## Run Function
+
+Run the transpilation process with given arguments.
+
+```c
 static int8_t
 run(t_args *args)
 {

srcs/map/core.c.md

@@ -1,9 +1,31 @@
+# core.c
+Core functions of the map feature.
+Handles initialization, addition, freeing, and growing of the map structure.
+
+---
+
+## Includes
 ```c
 #include <stdlib.h>
 
 #include "map.h"
 #include "internal/map_internal.h"
+```
 
+---
+
+## Function Descriptions
+
+### `map_init`
+Initializes the map structure.
+Every map structure must be initialized before use.
+They also must be freed with `map_free` when no longer needed.
+
+#### Parameters
+- `map`: Pointer to the map structure to initialize.
+
+##### Implementation
+```c
 void
 map_init(t_map *map)
 {
@@ -11,7 +33,20 @@ map_init(t_map *map)
 	map->count = 0;
 	map->capacity = 0;
 }
+```
 
+### `map_add`
+Adds a new range to the map structure.
+
+#### Parameters
+- `map`: Pointer to the map structure.
+- `src_start`: Start of the source range.
+- `src_end`: End of the source range.
+- `dst_start`: Start of the destination range.
+- `dst_end`: End of the destination range.
+
+#### Implementation
+```c
 void
 map_add(t_map *map, uint32_t src_start, uint32_t src_end,
 	uint32_t dst_start, uint32_t dst_end)
@@ -30,7 +65,16 @@ map_add(t_map *map, uint32_t src_start, uint32_t src_end,
 	range->dst_end = dst_end;
 	map->count++;
 }
+```
 
+### `map_free`
+Frees the resources allocated with the map structure.
+
+#### Parameters
+- `map`: Pointer to the map structure to free.
+
+#### Implementation
+```c
 void
 map_free(t_map *map)
 {
@@ -39,7 +83,21 @@ map_free(t_map *map)
 	map->count = 0;
 	map->capacity = 0;
 }
+```
 
+### `map_grow`
+Grows the capacity of the map structure.
+Multiplies the current capacity by 2, or sets it to an initial value if it's
+zero.
+
+#### Parameters
+- `map`: Pointer to the map structure to grow.
+
+#### Return Value
+Returns 0 on success, or 1 on memory allocation failure.
+
+#### Implementation
+```c
 int8_t
 map_grow(t_map *map)
 {

srcs/map/io.c.md

@@ -1,41 +1,42 @@
+# io.c
+Input/output functions for c-md mapping files.
+
+---
+
+## Includes
 ```c
 #include <stdio.h>
 
 #include "map.h"
 #include "internal/map_internal.h"
+```
 
-int8_t
-write_header(FILE *f, const char *source, const char *target)
-{
-	if (0 > fprintf(f, "C-MD MAP v1\n"))
-		return (1);
-	if (0 > fprintf(f, "source: %s\n", source))
-		return (1);
-	if (0 > fprintf(f, "target: %s\n", target))
-		return (1);
-	if (0 > fprintf(f, "---\n"))
-		return (1);
-	return (0);
-}
+---
 
-int8_t
-write_ranges(FILE *f, t_map *map)
-{
-	size_t		i;
-	t_range		*r;
+## Forward Declarations
+```c
+static int8_t	write_header(FILE *f, const char *source, const char *target);
+static int8_t	write_ranges(FILE *f, t_map *map);
+```
 
-	i = 0;
-	while (i < map->count)
-	{
-		r = &map->ranges[i];
-		if (0 > fprintf(f, "%u-%u:%u-%u\n",
-			r->src_start, r->src_end, r->dst_start, r->dst_end))
-			return (1);
-		i++;
-	}
-	return (0);
-}
+---
 
+## Function Descriptions
+
+### `map_write`
+Writes a c-md mapping file to the specified path.
+
+#### Parameters
+- `map`: Pointer to the mapping structure.
+- `path`: Pointer to the output file path string.
+- `source`: Pointer to the source file name string.
+- `target`: Pointer to the target file name string.
+
+#### Return Value
+Return 0 on success, or 1 on failure.
+
+##### Implementation
+```c
 int8_t
 map_write(t_map *map, const char *path, const char *source, const char *target)
 {
@@ -55,3 +56,62 @@ map_write(t_map *map, const char *path, const char *source, const char *target)
 	return (ret);
 }
 ```
+
+### `write_header`
+Writes the header of a c-md mapping file. (v1 format)
+
+#### Parameters
+- `f`: Pointer to the output file.
+- `source`: Pointer to the source file name string.
+- `target`: Pointer to the target file name string.
+
+#### Return Value
+Return 0 on success, or 1 on failure.
+
+#### Implementation
+```c
+int8_t
+write_header(FILE *f, const char *source, const char *target)
+{
+	if (0 > fprintf(f, "C-MD MAP v1\n"))
+		return (1);
+	if (0 > fprintf(f, "source: %s\n", source))
+		return (1);
+	if (0 > fprintf(f, "target: %s\n", target))
+		return (1);
+	if (0 > fprintf(f, "---\n"))
+		return (1);
+	return (0);
+}
+```
+
+### `write_ranges`
+Writes the ranges of a c-md mapping file.
+
+#### Parameters
+- `f`: Pointer to the output file.
+- `map`: Pointer to the mapping structure.
+
+#### Return Value
+Return 0 on success, or 1 on failure.
+
+#### Implementation
+```c
+int8_t
+write_ranges(FILE *f, t_map *map)
+{
+	size_t		i;
+	t_range		*r;
+
+	i = 0;
+	while (i < map->count)
+	{
+		r = &map->ranges[i];
+		if (0 > fprintf(f, "%u-%u:%u-%u\n",
+			r->src_start, r->src_end, r->dst_start, r->dst_end))
+			return (1);
+		i++;
+	}
+	return (0);
+}
+```

srcs/transpile/code.c.md

@@ -1,8 +1,33 @@
+# code.c
+Handle a single line of code by writing it to the output file and updating the
+state.
+
+---
+
+## Includes
 ```c
 #include <stdio.h>
 
 #include "internal/transpile_internal.h"
+```
 
+---
+
+## Function Descriptions
+
+### `handle_code_line`
+Handle a single line of code by writing it to the output file and updating the
+state.
+
+#### Parameters
+- `s`: Pointer to the current state structure.
+- `line`: Pointer to the line of code to be handled.
+
+#### Return Value
+Return 0 on success, or 1 on failure.
+
+#### Implementation
+```c
 int8_t
 handle_code_line(t_state *s, char *line)
 {

srcs/transpile/core.c.md

@@ -1,23 +1,43 @@
+# core.c
+Core funtion of the transpiler.
+Handles reading lines and processing them according to the current state.
+
+---
+
+## Includes
 ```c
 #include <stdlib.h>
 
 #include "transpile.h"
 #include "internal/transpile_internal.h"
 #include "utils.h"
+```
 
-int8_t
-process_line(t_state *s, char *line)
-{
-	s->src_line++;
-	if (0 == s->in_block && starts_with(line, "```"))
-		return (handle_fence_open(s, line));
-	if (1 == s->in_block && starts_with(line, "```"))
-		return (handle_fence_close(s));
-	if (1 == s->in_block)
-		return (handle_code_line(s, line));
-	return (0);
-}
+---
 
+## Forward Declarations
+
+```c
+static int8_t	process_line(t_state *s, char *line);
+```
+
+## Function Descriptions
+
+### `transpile`
+Transpiles input from a file to an output file based on the specified extension
+and mapping.
+
+#### Parameters
+- `in`: Pointer to the input file.
+- `out`: Pointer to the output file.
+- `ext`: Pointer to the file extension string.
+- `map`: Pointer to the mapping structure.
+
+#### Return Value
+Return 0 on success, or a non-zero error code on failure.
+
+#### Implementation
+```c
 int8_t
 transpile(FILE *in, FILE *out, const char *ext, t_map *map)
 {
@@ -38,3 +58,29 @@ transpile(FILE *in, FILE *out, const char *ext, t_map *map)
 	return (ret);
 }
 ```
+
+### `process_line`
+Processes a single line of input based on the current state.
+
+#### Parameters
+- `s`: Pointer to the current state structure.
+- `line`: Pointer to the line of text to process.
+
+#### Return Value
+Return 0 on success, or a non-zero error code on failure.
+
+#### Implementation
+```c
+static int8_t
+process_line(t_state *s, char *line)
+{
+	s->src_line++;
+	if (0 == s->in_block && starts_with(line, "```"))
+		return (handle_fence_open(s, line));
+	if (1 == s->in_block && starts_with(line, "```"))
+		return (handle_fence_close(s));
+	if (1 == s->in_block)
+		return (handle_code_line(s, line));
+	return (0);
+}
+

srcs/transpile/fence.c.md

@@ -1,3 +1,9 @@
+# fence.c
+Handles opening and closing of fenced code blocks in the transpilation process.
+
+---
+
+## Includes
 ```c
 #include <stdlib.h>
 #include <string.h>
@@ -5,7 +11,24 @@
 
 #include "internal/transpile_internal.h"
 #include "utils.h"
+```
 
+---
+
+## Function Descriptions
+
+### `handle_fence_open`
+Handles the opening of a fenced code block.
+
+#### Parameters
+- `s`: Pointer to the current transpilation state.
+- `line`: Pointer to the current line being processed.
+
+#### Return Value
+Returns `0` on success, `1` on error.
+
+#### Implementation
+```c
 int8_t
 handle_fence_open(t_state *s, char *line)
 {
@@ -32,7 +55,16 @@ handle_fence_open(t_state *s, char *line)
 	s->block_dst_start = s->dst_line + 1;
 	return (0);
 }
+```
 
+### `handle_fence_close`
+Handles the closing of a fenced code block.
+
+#### Parameters
+- `s`: Pointer to the current transpilation state.
+
+#### Implementation
+```c
 int8_t
 handle_fence_close(t_state *s)
 {

srcs/transpile/state.c.md

@@ -1,6 +1,29 @@
+# state.c
+
+Initialize the transpilation state structure.
+
+## Includes
 ```c
 #include "internal/transpile_internal.h"
+```
 
+---
+
+## Function Description
+### `state_init`
+
+Initialize the transpilation state structure.
+
+#### Parameters
+- `s`: Pointer to the state structure to initialize.
+- `in`: Input file pointer.
+- `out`: Output file pointer.
+- `ext`: Pointer to the extracted code fence extension string.
+- `map`: Pointer to the mapping structure.
+
+#### Implementation
+
+```c
 void
 state_init(t_state *s, FILE *in, FILE *out, const char *ext, t_map *map)
 {

srcs/utils/io/read_line.c.md

@@ -1,3 +1,12 @@
+# read_line.c
+
+Get a line from a file.
+depends on POSIX getline
+
+---
+
+## Includes
+
 ```c
 #define _POSIX_C_SOURCE 200809L
 
@@ -5,7 +14,29 @@
 #include <sys/types.h>
 
 #include "utils.h"
+```
 
+---
+
+## Function Description
+
+### `read_line`
+
+Get a line from a file.
+
+#### Parameter
+- `f`: Pointer to a `FILE` object representing the input file.
+
+#### Return Value
+
+Returns a pointer to the read line (dynamically allocated) or `NULL` on failure
+or end of file.
+
+Return value must be freed by the caller.
+
+#### Implementation
+
+```c
 char *
 read_line(FILE *f)
 {

srcs/utils/string/extract_fence_ext.c.md

@@ -1,10 +1,38 @@
+# extract_fence_ext.c
+
+Extract the extension from a markdown code fence.
+
+---
+
+## Includes
 ```c
 #include <stdlib.h>
 #include <string.h>
 #include <stdint.h>
 
 #include "utils.h"
+```
 
+---
+
+## Function Description
+
+### `extract_fence_ext`
+Extracts the extension from a markdown code fence string.
+
+#### Parameter
+- `fence`: Pointer to a null-terminated string representing the code fence.
+
+#### Return Value
+
+Returns a dynamically allocated string containing the extracted extension, or
+`NULL` if no extension is found or if the input is not a valid code fence.
+
+Return value must be freed by the caller.
+
+#### Implementation
+
+```c
 char *
 extract_fence_ext(const char *fence)
 {

srcs/utils/string/extract_file_ext.c.md

@@ -1,8 +1,34 @@
+# extract_file_ext.c
+
+Get the file extension from a given file path.
+
+---
+
+## Includes
 ```c
 #include <string.h>
 
 #include "utils.h"
+```
 
+---
+
+## Function Description
+
+### `extract_file_ext`
+Get the file extension from a given file path.
+
+#### Parameter
+- `path`: The file path string.
+
+#### Return Value
+
+Returns a pointer to the file extension within the path string, or `NULL` if
+no extension is found.
+
+#### Implementation
+
+```c
 const char *
 extract_file_ext(const char *path)
 {

srcs/utils/string/infer_ext_from_filename.c.md

@@ -1,8 +1,30 @@
+# infer_ext_from_filename.c
+Infer file extension from filename ending with .md
+
+---
+
+## Includes
 ```c
 #include <string.h>
 
 #include "utils.h"
+```
 
+---
+
+## Function Descriptions
+
+### `infer_ext_from_filename`
+Infer the file extension from a filename that ends with `.md`.
+
+#### Parameters
+- `path`: Pointer to the filename string.
+
+#### Return Value
+Returns a pointer to a static buffer containing the inferred extension, or
+`NULL` if no valid
+
+```c
 const char *
 infer_ext_from_filename(const char *path)
 {

srcs/utils/string/starts_with.c.md

@@ -1,9 +1,34 @@
+# starts_with.c
+
+Checks if a string starts with a given prefix.
+
+---
+
+## Includes
 ```c
 #include <string.h>
 #include <stdint.h>
 
 #include "utils.h"
+```
+---
 
+## Function Description
+
+### `starts_with`
+
+Checks if the string `str` starts with the substring `prefix`.
+
+#### Parameters
+- `str`: The main string to check.
+- `prefix`: The prefix to look for at the start of `str`.
+
+#### Return Value
+- Returns `1` (true) if `str` starts with `prefix`.
+- Returns `0` (false) otherwise.
+
+#### Implementation
+```c
 int8_t
 starts_with(const char *str, const char *prefix)
 {

srcs/validator/validator.c.md

@@ -1,9 +1,39 @@
+# validator.c
+
+Validate command-line arguments.
+
+---
+
+## Includes
 ```c
 #include <stddef.h>
 
 #include "validator.h"
 #include "utils.h"
+```
 
+---
+
+## Function Description
+
+### `validator_validate_args`
+
+Checks and validates the content of the `t_args` structure, ensuring required
+file input and extension arguments are consistent.
+
+#### Parameter
+- `args`: Pointer to a `t_args` structure containing command-line arguments.
+
+#### Return Codes
+
+| Code | Meaning													     |
+|------|-----------------------------------------------------------------|
+| 0	   | Arguments are valid											 |
+| 1	   | Both input file and extension are missing						 |
+| 2	   | Extension is missing and cannot be inferred from input filename |
+
+#### Implementation
+```c
 int8_t
 validator_validate_args(t_args *args)
 {