low hanging documentation

4 files changed, 61 insertions, 9 deletions

diff --git a/src/compiler.c b/src/compiler.c
index 68414c7..607618e 100644
--- a/src/compiler.c
+++ b/src/compiler.c
@@ -24,10 +24,20 @@
 #include <ek/path.h>
 #include <ek/res.h>
 
+/**
+ * Read whole file into a buffer and return pointer to buffer.
+ * Possibly kind of silly to have both \p file and \p f.
+ * Apparently there's no standardized way to get the file name of a
+ * file pointer.
+ *
+ * @param file Name of file to read.
+ * @param f File pointer.
+ * @return Pointer to buffer with file contents.
+ */
 static char *read_file(const char *file, FILE *f)
 {
 	fseek(f, 0, SEEK_END);
-	/* TODO: check how well standardized this actually is */
+	/** @todo check how well standardized this actually is */
 	long s = ftell(f);
 	if (s == LONG_MAX) {
 		error("%s might be a directory", file);
@@ -46,6 +56,16 @@ static char *read_file(const char *file, FILE *f)
 	return buf;
 }
 
+/**
+ * Helper for process_file(), actually processes the file
+ * after process_file() has done path lookups and working directory
+ * changes and whatnot.
+ *
+ * @param parent Parent file context. \c NULL if root file.
+ * @param public \c 1 if file is being imported publicly, \c 0 otherwise.
+ * @param file File name to process.
+ * @return \c 0 if processing was succesful, non-zero value otherwise.
+ */
 static int process(struct scope **parent, int public, const char *file)
 {
 	FILE *f = fopen(file, "rb");
@@ -99,7 +119,7 @@ static int process(struct scope **parent, int public, const char *file)
 int process_file(struct scope **scope, int public, const char *file)
 {
 	int res = -1;
-	/* TODO: report failure allocating stuff maybe? */
+	/** todo report failure allocating stuff maybe? */
 	struct res *r = res_create();
 	if (!r)
 		return -1;
@@ -153,7 +173,7 @@ int compile(const char *file) {
 	}
 
 	ret = actualize_main(root);
-	/* TODO: backend */
+	/** @todo backend */
 	destroy_scope(root);
 	return ret;
 }
diff --git a/src/debug.c b/src/debug.c
index 1be19af..017f07f 100644
--- a/src/debug.c
+++ b/src/debug.c
@@ -16,6 +16,12 @@
 
 #include <ek/debug.h>
 
+/**
+ * Get string representation of issue_level.
+ *
+ * @param level issue_level to get string representation for.
+ * @return \p level as a string.
+ */
 const char *issue_level_str(enum issue_level level)
 {
 	switch (level) {
@@ -27,9 +33,19 @@ const char *issue_level_str(enum issue_level level)
 	return "unknown";
 }
 
+/**
+ * Find position in file buffer where line number \p no
+ * starts. Lines are assumed to be one-indexed, with
+ * \p no = \c 0 and \p no = \c 1 both considered the first line.
+ *
+ * @param buf Buffer to look in.
+ * @param no Line number whose start to look for.
+ * @return Pointer to location in buffer where line number \p no
+ * starts.
+ */
 static const char *find_lineno(const char *buf, size_t no)
 {
-	if (no == 1)
+	if (no == 0 || no == 1)
 		return buf;
 
 	char c;
@@ -46,6 +62,13 @@ static const char *find_lineno(const char *buf, size_t no)
 	return buf;
 }
 
+/**
+ * Helper for printing out an issue.
+ *
+ * @param issue Issue context.
+ * @param fmt Format string. Follows standard printf() formatting.
+ * @param args Arguments for \p fmt.
+ */
 static void _issue(struct src_issue issue, const char *fmt, va_list args)
 {
 	/* get start and end of current line in buffer */
@@ -97,8 +120,6 @@ void src_issue(struct src_issue issue, const char *err_msg, ...)
 	va_end(args);
 }
 
-/* TODO: should really implement these better, the bad error messages are
- * starting to play a role in debugging */
 void semantic_error(struct file_ctx fctx, struct ast_node *node,
                     const char *fmt, ...)
 {
@@ -148,6 +169,12 @@ void internal_error(const char *fmt, ...)
 	va_end(args);
 }
 
+/**
+ * Workhorse for type_str().
+ *
+ * @param fp File pointer to write string representation to.
+ * @param type Type to generate string representation for.
+ */
 static void _type_str(FILE *fp, struct ast_node *type)
 {
 	if (!type)
@@ -269,6 +296,12 @@ char *type_str(struct ast_node *node)
 	return buf;
 }
 
+/**
+ * Workhorse for call_str().
+ *
+ * @param f File pointer to write string representation to.
+ * @param call Call to generate string representation for.
+ */
 static void _call_str(FILE *f, struct ast_node *call)
 {
 	struct ast_node *id = call->_call.id;
diff --git a/src/lexer.l b/src/lexer.l
index c855287..c30e802 100644
--- a/src/lexer.l
+++ b/src/lexer.l
@@ -9,11 +9,12 @@
 
 static void update_yylloc(struct parser *parser, YYLTYPE *lloc, const char *text)
 {
+	(void)parser;
+
 	lloc->first_line = lloc->last_line;
 	lloc->first_column = lloc->last_column;
 
 	for (size_t i = 0; text[i] != 0; ++i) {
-		parser->buf_offset++;
 		if (text[i] == '\n') {
 			lloc->last_line++;
 			/* flex uses 1 based indexing */
@@ -209,7 +210,6 @@ STRING		\"(\\.|[^"\\])*\"
 	issue.loc = to_src_loc(yylloc);
 	issue.fctx.fbuf = parser->buf;
 	issue.fctx.fname = parser->fname;
-	issue.offset = parser->buf_offset;
 	src_issue(issue, "Unexpected token: %s", yytext);
 	parser->failed = true;
 }
diff --git a/src/parser_helper.c b/src/parser_helper.c
index 15dd6e8..5a90df8 100644
--- a/src/parser_helper.c
+++ b/src/parser_helper.c
@@ -87,7 +87,6 @@ void yyerror(YYLTYPE *yylloc, void *lexer, struct parser *parser,
 	issue.loc = to_src_loc(yylloc);
 	issue.fctx.fbuf = parser->buf;
 	issue.fctx.fname = parser->fname;
-	issue.offset = parser->buf_offset;
 	src_issue(issue, msg);
 }