--- a/src/irc_line.h	Tue Mar 10 03:48:00 2009 +0200
+++ b/src/irc_line.h	Tue Mar 10 19:52:38 2009 +0200
@@ -1,46 +1,58 @@
 #ifndef IRC_LINE_H
 #define IRC_LINE_H
 
+/**
+ * @file
+ *
+ * The low-level IRC protocol unit is a line, with prefix, command and arguments
+ */
 #include "error.h"
 
-/*
+/**
  * The maximum length of a line, without terminating CRLF
  */
 #define IRC_LINE_MAX 510
 
-/*
+/**
  * The maximum number of arguments for a single command
  */
 #define IRC_ARG_MAX 15
 
-/*
+/**
  * Chars that are invalid inside of tokens
  */
 #define IRC_TOKEN_INVALID "\r\n\n "
 #define IRC_TOKEN_TRAILING_INVALID "\r\n\n"
 
-/*
- * Low-level IRC protocol unit is a line with its bits
+/**
+ * Low-level IRC protocol unit
  */
 struct irc_line {
-    /* The message source, either a server name or a nickmask */
+    /** The message source, either a server name or a nickmask */
     const char *prefix;
 
-    /* The command, either a numeric or a primary command */
+    /** The command, either a numeric or a primary command */
     const char *command;
 
-    /* The arguments, with unused ones set to NULL */
+    /** The arguments, with unused ones set to NULL */
     const char *args[IRC_ARG_MAX];
 };
 
-/*
+/**
  * Parse an IRC message to fill in an irc_line. This mutates the value of data (to insert NULs between tokens), and
  * stores pointers into this data into the irc_line.
+ *
+ * The irc_line will have the first N args values set to valid values, and all the rest set to NULL.
  */
 err_t irc_line_parse (struct irc_line *line, char *data);
 
-/*
+/**
  * Formats an irc_line as a protocol line into the given buffer (which should hold at least IRC_LINE_MAX bytes).
+ *
+ * The irc_line.args are ignored from the first NULL argument onwards.
+ *
+ * An error is returned if a token has an invalid value (e.g. a space in the command or an argument other than the last
+ * one), or if the resulting line is too long.
  */
 err_t irc_line_build (const struct irc_line *line, char *buf);