low hanging documentation

6 files changed, 221 insertions, 6 deletions

diff --git a/include/ek/actualize.h b/include/ek/actualize.h
index 18755b1..9cee764 100644
--- a/include/ek/actualize.h
+++ b/include/ek/actualize.h
@@ -7,9 +7,8 @@
 /**
  * @file actualize.h
  *
- * Actualization stuff, that is stuff needed for turning raw AST
- * into processed AST that can be passed to a backend to generate
- * code.
+ * Actualization stuff  needed for turning raw AST
+ * into processed AST that can be passed to a backend to generate code.
  */
 
 #include <assert.h>
diff --git a/include/ek/compiler.h b/include/ek/compiler.h
index 8e3d221..32fc218 100644
--- a/include/ek/compiler.h
+++ b/include/ek/compiler.h
@@ -12,7 +12,25 @@
 
 #include <ek/scope.h>
 
+/**
+ * Compile a root file.
+ * A root file is a file given on the command line, and is assumed to
+ * create a file tree that eventually results in a binary.
+ *
+ * @param file Root file to compile.
+ * @return \c 0 if compilation was succesful, otherwise some non-zero value.
+ */
 int compile(const char *file);
+
+/**
+ * Process a file, i.e. lex, parse and generate raw AST.
+ *
+ * @param parent Parent scope of file from which \p file is imported.
+ * \c NULL if root file.
+ * @param public \c 1 if \p file should be publicly imported, \c 0 otherwise.
+ * @param file File to process.
+ * @return \c 0 if compilation was succesful, otherwise some non-zero value.
+ */
 int process_file(struct scope **parent, int public, const char *file);
 
 #endif /* EK_COMPILER_H */
diff --git a/include/ek/debug.h b/include/ek/debug.h
index 7dca003..d222cf4 100644
--- a/include/ek/debug.h
+++ b/include/ek/debug.h
@@ -15,49 +15,139 @@
 #include <ek/ast.h>
 
 #if DEBUG
+/**
+ * Print debugging message. Only active if \c DEBUG is defined,
+ *
+ * @param x Format string. Follows standard printf() formatting.
+ */
 #define debug(x, ...) \
 	do {fprintf(stderr, "debug: " x "\n",##__VA_ARGS__);} while(0)
 #else
 #define debug(x, ...)
 #endif
 
+/**
+ * Print error message.
+ *
+ * @param x Format string. Follows standard printf() formatting.
+ */
 #define error(x, ...) \
 	do {fprintf(stderr, "error: " x "\n",##__VA_ARGS__);} while(0)
 
+/**
+ * Print warning message.
+ *
+ * @param x Format string. Follows standard printf() formatting.
+ */
 #define warn(x, ...) \
 	do {fprintf(stderr, "warn: " x "\n",##__VA_ARGS__);} while(0)
 
+/**
+ * Print info message.
+ *
+ * @param x Format string. Follows standard printf() formatting.
+ */
 #define info(x, ...) \
 	do {fprintf(stderr, "info: " x "\n",##__VA_ARGS__);} while(0)
 
 
+/** Keeps track of file name and file buffer. */
 struct file_ctx {
+	/** File name. */
 	const char *fname;
+	/** File buffer. */
 	const char *fbuf;
 };
 
+/**
+ * Generate string representation of type.
+ *
+ * @param type Type to generate string representation of.
+ * @return \p type as string.
+ */
 char *type_str(struct ast_node *type);
+
+/**
+ * Generate string representation of call.
+ *
+ * @param call Call to generate string representation of.
+ * @return \p call as string.
+ */
 char *call_str(struct ast_node *call);
+
+/**
+ * Print info that relates to a specific AST node.
+ * Recommended for situations where it may be useful to clarify some
+ * previous error or warning.
+ *
+ * @param ctx File context \p node was generated from.
+ * @param node AST node to print message with.
+ * @param fmt Format string. Follows standard printf() formatting.
+ */
 void semantic_info(struct file_ctx ctx, struct ast_node *node, const char *fmt,
                    ...);
+
+/**
+ * Print warning that relates to a specific AST node.
+ * Recommended for situations where the user wrote some shady code
+ * and it might be unclear what was meant.
+ *
+ * The language itself tries to avoid such situations, and as such warnings
+ * should probably be avoided in favor of errors. Still, I can imagine that
+ * there are situations where warnings can be useful, so it's provided.
+ *
+ * @param ctx File context \p node was generated from.
+ * @param node AST node to print message with.
+ * @param fmt Format string. Follows standard printf() formatting.
+ */
 void semantic_warn(struct file_ctx ctx, struct ast_node *node, const char *fmt,
                    ...);
+
+/**
+ * Print warning that relates to a specific AST node.
+ * Recommended for situations where the user messed up.
+ *
+ * @param ctx File context \p node was generated from.
+ * @param node AST node to print message with.
+ * @param fmt Format string. Follows standard printf() formatting.
+ */
 void semantic_error(struct file_ctx ctx, struct ast_node *node, const char *fmt,
                     ...);
+
+/**
+ * Print internal error.
+ * Recommended for situations where the developer (probably me) messed up.
+ *
+ * @param fmt Format string. Follows standard printf() formatting.
+ */
 void internal_error(const char *fmt, ...);
 
+/** Issue categorization. */
 enum issue_level {
+	/** Information. */
 	SRC_INFO,
+	/** Warning. */
 	SRC_WARN,
+	/** Error. */
 	SRC_ERROR
 };
 
+/** Context for issue in user code. */
 struct src_issue {
+	/** How bad the issue is. */
 	enum issue_level level;
+	/** Where the issue happened relative to file buffer. */
 	struct src_loc loc;
+	/** File context issue happened in. */
 	struct file_ctx fctx;
-	size_t offset;
 };
 
+/**
+ * Print a source issue.
+ *
+ * @param issue Context for issue.
+ * @param err_msg Format string. Follows standard printf() formatting.
+ */
 void src_issue(struct src_issue issue, const char *err_msg, ...);
+
 #endif /* EK_DEBUG_H */
diff --git a/include/ek/imports.h b/include/ek/imports.h
index 801eb06..43603c4 100644
--- a/include/ek/imports.h
+++ b/include/ek/imports.h
@@ -9,13 +9,25 @@
  *
  * File import handling.
  * Currently mostly unimplemented, but intended to keep track
- * of which files have been imported.
+ * of where to find files for import.
  */
 
 #include <stdbool.h>
 
+/**
+ * Add import path to search for files in.
+ *
+ * @param dir Directory to search files in. Either absolute or relative.
+ */
 void add_import_path(const char *dir);
+
+/**
+ * Search for \p file in import path.
+ * @todo implement.
+ *
+ * @param file File name to search for.
+ * @return Full path to \p file if found, \c NULL otherwise.
+ */
 const char *find_import(const char *file);
-bool already_imported(const char *file);
 
 #endif /* EK_IMPORTS_H */
diff --git a/include/ek/path.h b/include/ek/path.h
index 2ddfb4c..2e15932 100644
--- a/include/ek/path.h
+++ b/include/ek/path.h
@@ -10,8 +10,29 @@
  * Path handling helpers.
  */
 
+/**
+ * Get basename of file path.
+ * E.g. src/some/file.c -> file.c
+ *
+ * @param file File path to get basename from.
+ * @return Basename of \p file.
+ */
 char *ek_basename(const char *file);
+
+/**
+ * Get directory name of path.
+ * E.g. src/some/file.c -> src/some
+ *
+ * @param file File path to get dirname from.
+ * @return Dirname of \p file.
+ */
 char *ek_dirname(const char *file);
+
+/**
+ * Get current working directory.
+ *
+ * @return Current working directory.
+ */
 char *ek_cwdname();
 
 #endif /* EK_PATH */
diff --git a/include/ek/string.h b/include/ek/string.h
index 5c561a7..bbe8779 100644
--- a/include/ek/string.h
+++ b/include/ek/string.h
@@ -9,28 +9,103 @@
  *
  * String handling helper stuff.
  * At the moment mostly unused.
+ * Doesn't implement short string optimizations or anything like that for now.
  */
 
 #include <stddef.h>
 #include <string.h>
 #include <stdbool.h>
 
+/** Simple representation of a string. */
 struct string {
+	/** Lenght of string. */
 	size_t len;
+	/** String buffer. */
 	char *buf;
 };
 
+/**
+ * Create new string from null terminated character array.
+ * Allocates a string object on the heap and copies \p s into it.
+ *
+ * @param s Null terminated character array.
+ * @return \p s as a string.
+ */
 struct string *new_string(const char *s);
+
+/**
+ * Destroy previously created string.
+ * Frees the string and anything associated with it.
+ *
+ * @param s String to destroy.
+ */
 void destroy_string(struct string *s);
 
+/**
+ * Append a character to a string.
+ *
+ * @param s String to append \c to.
+ * @param c Character to append to \p s.
+ * @return \c 0 if appending succeeded, non-zero otherwise.
+ */
 int str_append(struct string *s, char c);
+
+/**
+ * Concatenate a string and a null terminated character array.
+ * Essentially adds \p c to the end of \p s.
+ *
+ * @param s String to concatenate \p c with.
+ * @param c Null terminated character array to concatenate with \p s.
+ * @return \c 0 if concatenation succeeded, non-zero otherwise.
+ */
 int str_concat(struct string *s, const char *c);
+
+/**
+ * Add \p c to the end of \p s.
+ *
+ * @param s String to add \p c to.
+ * @param c String to att to \p s.
+ * @return \c 0 if addition succeedes, non-zero otherwise.
+ */
 int str_add(struct string *s, struct string *c);
 
+/**
+ * Get character at index \p i in \p s.
+ *
+ * @todo implement, range checking?
+ *
+ * @param s String to index into.
+ * @param i Index of character to get.
+ * @return Character at \p i in \p s.
+ */
 char str_index(struct string *s, size_t i);
+
+/**
+ * Get character at index \p i from the end of \p s.
+ *
+ * @todo implement, range checking?
+ *
+ * @param s String to index into?
+ * @param i Index of character from the end to get.
+ * @return Character at \p i from the end of \p s.
+ */
 char str_rindex(struct string *s, size_t i);
 
+/**
+ * Compare string with null-terminated character array.
+ * Essentially a wrapper around strncmp().
+ *
+ * @param s String to compare against \p c.
+ * @param c Null-terminated array to compare against \p s.
+ * @return \c true if identical, \c false otherwise.
+ */
 bool str_compare(struct string *s, const char *c);
+
+/**
+ * Clear content of string.
+ *
+ * @param s String to clear content of.
+ */
 void str_clear(struct string *s);
 
 #endif /* EK_STRING_H */