Update docstrings

@@ -76,7 +76,7 @@ _get_address_part (const char *func_name, address_get_fp fun,
 
 SCM_DEFINE (scm_mu_address_get_personal, "mu-address-get-personal", 1, 1, 0,
 	    (SCM ADDRESS, SCM NUM),
-	    "Return personal part of an email address.\n")
+	    "Return personal part of the NUMth email address from ADDRESS.\n")
 #define FUNC_NAME s_scm_mu_address_get_personal
 {
   return _get_address_part (FUNC_NAME, 
@@ -86,7 +86,7 @@ SCM_DEFINE (scm_mu_address_get_personal, "mu-address-get-personal", 1, 1, 0,
 
 SCM_DEFINE (scm_mu_address_get_comments, "mu-address-get-comments", 1, 1, 0,
 	    (SCM ADDRESS, SCM NUM),
-	    "Return comment part of an email address.\n")
+	    "Return comment part of the NUMth email address from ADDRESS.\n")
 #define FUNC_NAME s_scm_mu_address_get_comments
 {
   return _get_address_part (FUNC_NAME, 
@@ -96,7 +96,7 @@ SCM_DEFINE (scm_mu_address_get_comments, "mu-address-get-comments", 1, 1, 0,
 
 SCM_DEFINE (scm_mu_address_get_email, "mu-address-get-email", 1, 1, 0,
 	    (SCM ADDRESS, SCM NUM),
-	    "Return email part of an email address.\n")
+	    "Return email part of the NUMth email address from ADDRESS.\n")
 #define FUNC_NAME s_scm_mu_address_get_email
 {
   return _get_address_part (FUNC_NAME, 
@@ -106,7 +106,7 @@ SCM_DEFINE (scm_mu_address_get_email, "mu-address-get-email", 1, 1, 0,
 
 SCM_DEFINE (scm_mu_address_get_domain, "mu-address-get-domain", 1, 1, 0,
 	    (SCM ADDRESS, SCM NUM),
-	    "Return domain part of an email address.\n")
+	    "Return domain part of the NUMth email address from ADDRESS.\n")
 #define FUNC_NAME s_scm_mu_address_get_domain
 {
   return _get_address_part (FUNC_NAME, 
@@ -116,7 +116,7 @@ SCM_DEFINE (scm_mu_address_get_domain, "mu-address-get-domain", 1, 1, 0,
 
 SCM_DEFINE (scm_mu_address_get_local, "mu-address-get-local", 1, 1, 0,
 	    (SCM ADDRESS, SCM NUM),
-	    "Return local part of an email address.\n")
+	    "Return local part of the NUMth email address from ADDRESS.\n")
 #define FUNC_NAME s_scm_mu_address_get_local
 {
   return _get_address_part (FUNC_NAME, 
@@ -126,7 +126,7 @@ SCM_DEFINE (scm_mu_address_get_local, "mu-address-get-local", 1, 1, 0,
 
 SCM_DEFINE (scm_mu_address_get_count, "mu-address-get-count", 1, 0, 0,
 	    (SCM ADDRESS),
-	    "Return number of parts in email address.\n")
+	    "Return number of parts in email address ADDRESS.\n")
 #define FUNC_NAME s_scm_mu_address_get_count
 {
   mu_address_t addr;
@@ -149,8 +149,8 @@ SCM_DEFINE (scm_mu_address_get_count, "mu-address-get-count", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_username_to_email, "mu-username->email", 0, 1, 0,
 	    (SCM NAME),
-	    "Deduce the email from the username. If NAME is omitted, current username\n"
-	    "is assumed\n")
+"Deduce user's email address from his username. If NAME is omitted, \n"
+"current username is assumed\n")
 #define FUNC_NAME s_scm_mu_username_to_email
 {
   const char *name;

@@ -22,7 +22,8 @@
 
 SCM_DEFINE (scm_mu_openlog, "mu-openlog", 3, 0, 0,
 	   (SCM IDENT, SCM OPTION, SCM FACILITY),
-	   "Opens a connection to the system logger for Guile program.")
+"Opens a connection to the system logger for Guile program.\n"
+"IDENT, OPTION and FACILITY have the same meaning as in openlog(3)")
 #define FUNC_NAME s_scm_mu_openlog
 {
   const char *ident;
@@ -57,7 +58,7 @@ SCM_DEFINE (scm_mu_openlog, "mu-openlog", 3, 0, 0,
 
 SCM_DEFINE (scm_mu_logger, "mu-logger", 2, 0, 0,
 	   (SCM PRIO, SCM TEXT),
-	   "Generates a log message to be distributed via syslogd.")
+	   "Distributes TEXT via syslogd priority PRIO.")
 #define FUNC_NAME s_scm_mu_logger
 {
   int prio;
@@ -79,7 +80,7 @@ SCM_DEFINE (scm_mu_logger, "mu-logger", 2, 0, 0,
 
 SCM_DEFINE (scm_mu_closelog, "mu-closelog", 0, 0, 0,
 	   (),
-	   "Closes the channel to the system logger open by mu-openlog.")
+	   "Closes the channel to the system logger opened by @code{mu-openlog}.")
 #define FUNC_NAME s_scm_mu_closelog
 {
   closelog ();

@@ -106,7 +106,8 @@ mu_scm_is_mailbox (SCM scm)
 
 SCM_DEFINE (scm_mu_mail_directory, "mu-mail-directory", 0, 1, 0,
 	    (SCM URL), 
-            "")
+"If URL is given, sets it as a name of the user's mail directory.\n"
+"Returns the current value of the mail directory.")
 #define FUNC_NAME s_scm_mu_mail_directory
 {
   if (!SCM_UNBNDP (URL))
@@ -120,7 +121,8 @@ SCM_DEFINE (scm_mu_mail_directory, "mu-mail-directory", 0, 1, 0,
 
 SCM_DEFINE (scm_mu_folder_directory, "mu-folder-directory", 0, 1, 0,
 	    (SCM URL), 
-            "")
+"If URL is given, sets it as a name of the user's folder directory.\n"
+"Returns the current value of the folder directory.")
 #define FUNC_NAME s_scm_mu_folder_directory
 {
   if (!SCM_UNBNDP (URL))
@@ -134,14 +136,24 @@ SCM_DEFINE (scm_mu_folder_directory, "mu-folder-directory", 0, 1, 0,
 
 SCM_DEFINE (scm_mu_mailbox_open, "mu-mailbox-open", 2, 0, 0,
 	    (SCM URL, SCM MODE), 
-            "Opens a mailbox specified by URL.")
+"Opens the mailbox specified by URL. MODE is a string, consisting of\n"
+"the characters described below, giving the access mode for the mailbox\n"
+"\n"
+"@multitable @columnfractions 0.20 0.70\n"
+"@headitem MODE @tab Meaning\n"
+"@item r @tab Open for reading.\n"
+"@item w @tab Open for writing.\n"
+"@item a @tab Open for appending to the end of the mailbox.\n"
+"@item c @tab Create the mailbox if it does not exist.\n"
+"@end multitable\n"
+)
 #define FUNC_NAME s_scm_mu_mailbox_open
 {
   mu_mailbox_t mbox = NULL;
   const char *mode_str;
   int mode = 0;
   int status;
-  
+
   SCM_ASSERT (scm_is_string (URL), URL, SCM_ARG1, FUNC_NAME);
   SCM_ASSERT (scm_is_string (MODE), MODE, SCM_ARG2, FUNC_NAME);
 
@@ -186,7 +198,7 @@ SCM_DEFINE (scm_mu_mailbox_open, "mu-mailbox-open", 2, 0, 0,
 #undef FUNC_NAME
 
 SCM_DEFINE (scm_mu_mailbox_close, "mu-mailbox-close", 1, 0, 0,
-	    (SCM MBOX), "Closes mailbox MBOX")
+	    (SCM MBOX), "Closes mailbox MBOX.")
 #define FUNC_NAME s_scm_mu_mailbox_close
 {
   struct mu_mailbox *mum;
@@ -201,25 +213,31 @@ SCM_DEFINE (scm_mu_mailbox_close, "mu-mailbox-close", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_mailbox_get_url, "mu-mailbox-get-url", 1, 0, 0,
 	    (SCM MBOX), 
-            "Returns the URL of the mailbox.")
+            "Returns url of the mailbox MBOX.")
 #define FUNC_NAME s_scm_mu_mailbox_get_url
 {
   struct mu_mailbox *mum;
   mu_url_t url;
-  
+  int status;
+ 
   SCM_ASSERT (mu_scm_is_mailbox (MBOX), MBOX, SCM_ARG1, FUNC_NAME);
   mum = (struct mu_mailbox *) SCM_CDR (MBOX);
-  mu_mailbox_get_url (mum->mbox, &url);
+  status = mu_mailbox_get_url (mum->mbox, &url);
+  if (status)
+    mu_scm_error (FUNC_NAME, status,
+                  "Cannot get mailbox url",
+                  SCM_BOOL_F);
+
   return scm_makfrom0str (mu_url_to_string (url));
 }
 #undef FUNC_NAME
 
 SCM_DEFINE (scm_mu_mailbox_get_port, "mu-mailbox-get-port", 2, 0, 0,
 	    (SCM MBOX, SCM MODE),
-	    "Returns a port associated with the contents of the MBOX.\n"
-	    "MODE is a string defining operation mode of the stream. It may\n"
-	    "contain any of the two characters: \"r\" for reading, \"w\" for\n"
-	    "writing.\n")
+"Returns a port associated with the contents of the MBOX.\n"
+"MODE is a string defining operation mode of the stream. It may\n"
+"contain any of the two characters: @samp{r} for reading, @samp{w} for\n"
+"writing.\n")
 #define FUNC_NAME s_scm_mu_mailbox_get_port
 {
   struct mu_mailbox *mum;
@@ -240,7 +258,8 @@ SCM_DEFINE (scm_mu_mailbox_get_port, "mu-mailbox-get-port", 2, 0, 0,
 #undef FUNC_NAME
 
 SCM_DEFINE (scm_mu_mailbox_get_message, "mu-mailbox-get-message", 2, 0, 0,
-	    (SCM MBOX, SCM MSGNO), "Retrieve from MBOX message # MSGNO.")
+            (SCM MBOX, SCM MSGNO), 
+"Retrieve from message #MSGNO from the mailbox MBOX.")
 #define FUNC_NAME s_scm_mu_mailbox_get_message
 {
   size_t msgno;
@@ -265,7 +284,8 @@ SCM_DEFINE (scm_mu_mailbox_get_message, "mu-mailbox-get-message", 2, 0, 0,
 #undef FUNC_NAME
 
 SCM_DEFINE (scm_mu_mailbox_messages_count, "mu-mailbox-messages-count", 1, 0, 0,
-	    (SCM MBOX), "Returns number of messages in the mailbox.")
+	    (SCM MBOX), 
+"Returns number of messages in the mailbox MBOX.")
 #define FUNC_NAME s_scm_mu_mailbox_messages_count
 {
   struct mu_mailbox *mum;
@@ -285,7 +305,8 @@ SCM_DEFINE (scm_mu_mailbox_messages_count, "mu-mailbox-messages-count", 1, 0, 0,
 #undef FUNC_NAME
 
 SCM_DEFINE (scm_mu_mailbox_expunge, "mu-mailbox-expunge", 1, 0, 0,
-	    (SCM MBOX), "Expunges deleted messages from the mailbox.")
+	    (SCM MBOX), 
+"Expunges deleted messages from the mailbox MBOX.")
 #define FUNC_NAME s_scm_mu_mailbox_expunge
 {
   struct mu_mailbox *mum;
@@ -302,27 +323,9 @@ SCM_DEFINE (scm_mu_mailbox_expunge, "mu-mailbox-expunge", 1, 0, 0,
 }
 #undef FUNC_NAME
 
-SCM_DEFINE (scm_mu_mailbox_url, "mu-mailbox-url", 1, 0, 0,
-	    (SCM MBOX), "Returns the URL of the mailbox")
-#define FUNC_NAME s_scm_mu_mailbox_url
-{
-  struct mu_mailbox *mum;
-  mu_url_t url;
-  int status;
-  
-  SCM_ASSERT (mu_scm_is_mailbox (MBOX), MBOX, SCM_ARG1, FUNC_NAME);
-  mum = (struct mu_mailbox *) SCM_CDR (MBOX);
-  mu_mailbox_get_url (mum->mbox, &url);
-  if (status)
-    mu_scm_error (FUNC_NAME, status,
-		  "Cannot get mailbox URL",
-		  SCM_BOOL_F);
-  return scm_makfrom0str (mu_url_to_string (url));
-}
-#undef FUNC_NAME
-
 SCM_DEFINE (scm_mu_mailbox_append_message, "mu-mailbox-append-message", 2, 0, 0,
-	    (SCM MBOX, SCM MESG), "Appends the message to the mailbox")
+	    (SCM MBOX, SCM MESG),
+"Appends message MESG to the mailbox MBOX.")
 #define FUNC_NAME s_scm_mu_mailbox_append_message
 {
   struct mu_mailbox *mum;

@@ -176,7 +176,7 @@ mu_scm_is_message (SCM scm)
 
 SCM_DEFINE (scm_mu_message_create, "mu-message-create", 0, 0, 0,
 	    (),
-	    "Creates an empty message.")
+	    "Creates an empty message.\n")
 #define FUNC_NAME s_scm_mu_message_create
 {
   mu_message_t msg;
@@ -188,7 +188,7 @@ SCM_DEFINE (scm_mu_message_create, "mu-message-create", 0, 0, 0,
 /* FIXME: This changes envelope date */
 SCM_DEFINE (scm_mu_message_copy, "mu-message-copy", 1, 0, 0,
 	    (SCM MESG),
-	    "Creates the copy of the given message.\n")
+	    "Creates the copy of the message MESG.\n")
 #define FUNC_NAME s_scm_mu_message_copy
 {
   mu_message_t msg, newmsg;
@@ -249,7 +249,7 @@ SCM_DEFINE (scm_mu_message_copy, "mu-message-copy", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_destroy, "mu-message-destroy", 1, 0, 0,
 	    (SCM MESG),
-	    "Destroys the message.")
+	    "Destroys the message MESG.")
 #define FUNC_NAME s_scm_mu_message_destroy
 {
   struct mu_message *mum;
@@ -263,10 +263,10 @@ SCM_DEFINE (scm_mu_message_destroy, "mu-message-destroy", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_set_header, "mu-message-set-header", 3, 1, 0,
 	    (SCM MESG, SCM HEADER, SCM VALUE, SCM REPLACE),
-	    "Sets new VALUE to the header HEADER of the message MESG.\n"
-	    "If the HEADER is already present in the message its value\n"
-	    "is replaced with the suplied one iff the optional REPLACE is\n"
-	    "#t. Otherwise new header is created and appended.")
+"Sets new VALUE to the header HEADER of the message MESG.\n"
+"If HEADER is already present in the message its value\n"
+"is replaced with the suplied one iff the optional REPLACE is\n"
+"#t. Otherwise, a new header is created and appended.")
 #define FUNC_NAME s_scm_mu_message_set_header
 {
   mu_message_t msg;
@@ -306,7 +306,7 @@ SCM_DEFINE (scm_mu_message_set_header, "mu-message-set-header", 3, 1, 0,
 
 SCM_DEFINE (scm_mu_message_get_size, "mu-message-get-size", 1, 0, 0,
 	    (SCM MESG),
-	    "Returns the size of the given message.")
+	    "Returns the size of the message MESG\n.")
 #define FUNC_NAME s_scm_mu_message_get_size
 {
   mu_message_t msg;
@@ -320,7 +320,7 @@ SCM_DEFINE (scm_mu_message_get_size, "mu-message-get-size", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_get_lines, "mu-message-get-lines", 1, 0, 0,
 	    (SCM MESG),
-	    "Returns number of lines in the given message.")
+	    "Returns number of lines in the given message.\n")
 #define FUNC_NAME s_scm_mu_message_get_lines
 {
   mu_message_t msg;
@@ -341,7 +341,7 @@ SCM_DEFINE (scm_mu_message_get_lines, "mu-message-get-lines", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_get_sender, "mu-message-get-sender", 1, 0, 0,
 	    (SCM MESG),
-	    "Returns the sender email address for the message MESG.")
+	    "Returns email address of the sender of the message MESG.\n")
 #define FUNC_NAME s_scm_mu_message_get_sender
 {
   mu_message_t msg;
@@ -368,7 +368,7 @@ SCM_DEFINE (scm_mu_message_get_sender, "mu-message-get-sender", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_get_header, "mu-message-get-header", 2, 0, 0,
 	    (SCM MESG, SCM HEADER),
-	    "Returns the header value of the HEADER in the MESG.")
+	    "Returns value of the header HEADER from the message MESG.\n")
 #define FUNC_NAME s_scm_mu_message_get_header
 {
   mu_message_t msg;
@@ -424,9 +424,8 @@ string_sloppy_member (SCM lst, char *name)
 
 SCM_DEFINE (scm_mu_message_get_header_fields, "mu-message-get-header-fields", 1, 1, 0,
 	    (SCM MESG, SCM HEADERS),
-	    "Returns the list of headers in the MESG. If optional HEADERS is\n"
-	    "specified it should be a list of header names to restrict return\n"
-	    "value to.\n")
+"Returns the list of headers in the message MESG. Optional argument\n" 
+"HEADERS gives a list of header names to restrict return value to.\n")
 #define FUNC_NAME s_scm_mu_message_get_header_fields
 {
   size_t i, nfields = 0;
@@ -498,11 +497,12 @@ SCM_DEFINE (scm_mu_message_get_header_fields, "mu-message-get-header-fields", 1,
   
 SCM_DEFINE (scm_mu_message_set_header_fields, "mu-message-set-header-fields", 2, 1, 0,
 	    (SCM MESG, SCM LIST, SCM REPLACE),
-	    "Set the headers in the message MESG from LIST\n"
-	    "LIST is a list of (cons HEADER VALUE)\n"
-	    "Optional parameter REPLACE spceifies whether the new header\n"
-	    "values should replace the headers already present in the\n"
-	    "message.")
+"Set the headers in the message MESG from LIST\n"
+"LIST is a list of conses (cons HEADER VALUE).  The function sets\n"
+"these headers in the message MESG.\n"
+"Optional parameter REPLACE specifies whether the new header\n"
+"values should replace the headers already present in the\n"
+"message.")
 #define FUNC_NAME s_scm_mu_message_set_header_fields
 {
   mu_message_t msg;
@@ -554,8 +554,9 @@ SCM_DEFINE (scm_mu_message_set_header_fields, "mu-message-set-header-fields", 2,
 
 SCM_DEFINE (scm_mu_message_delete, "mu-message-delete", 1, 1, 0,
 	    (SCM MESG, SCM FLAG),
-	    "Mark given message as deleted. Optional FLAG allows to toggle deleted mark\n"
-	    "The message is deleted if it is #t and undeleted if it is #f")
+"Mark the message MESG as deleted. Optional argument FLAG allows to toggle\n"
+"deletion mark. The message is deleted if it is @code{#t} and undeleted if\n"
+"it is @code{#f}")
 #define FUNC_NAME s_scm_mu_message_delete
 {
   mu_message_t msg;
@@ -591,7 +592,7 @@ SCM_DEFINE (scm_mu_message_delete, "mu-message-delete", 1, 1, 0,
 
 SCM_DEFINE (scm_mu_message_get_flag, "mu-message-get-flag", 2, 0, 0,
 	    (SCM MESG, SCM FLAG),
-	    "Return value of the attribute FLAG.")
+"Return value of the attribute FLAG of the message MESG.")
 #define FUNC_NAME s_scm_mu_message_get_flag
 {
   mu_message_t msg;
@@ -652,8 +653,8 @@ SCM_DEFINE (scm_mu_message_get_flag, "mu-message-get-flag", 2, 0, 0,
 
 SCM_DEFINE (scm_mu_message_set_flag, "mu-message-set-flag", 2, 1, 0,
 	    (SCM MESG, SCM FLAG, SCM VALUE),
-	    "Set the given attribute of the message. If optional VALUE is #f, the\n"
-	    "attribute is unset.")
+"Set the attribute FLAG of the message MESG. If optional VALUE is #f, the\n"
+"attribute is unset.")
 #define FUNC_NAME s_scm_mu_message_set_flag
 {
   mu_message_t msg;
@@ -751,7 +752,7 @@ SCM_DEFINE (scm_mu_message_set_flag, "mu-message-set-flag", 2, 1, 0,
 
 SCM_DEFINE (scm_mu_message_get_user_flag, "mu-message-get-user-flag", 2, 0, 0,
 	    (SCM MESG, SCM FLAG),
-	    "Returns value of the user attribute FLAG.")
+"Return the value of the user attribute FLAG from the message MESG.")
 #define FUNC_NAME s_scm_mu_message_get_user_flag
 {
   mu_message_t msg;
@@ -773,8 +774,8 @@ SCM_DEFINE (scm_mu_message_get_user_flag, "mu-message-get-user-flag", 2, 0, 0,
 
 SCM_DEFINE (scm_mu_message_set_user_flag, "mu-message-set-user-flag", 2, 1, 0,
 	    (SCM MESG, SCM FLAG, SCM VALUE),
-	    "Set the given user attribute of the message. If optional VALUE is\n"
-	    "#f, the attribute is unset.")
+"Set the given user attribute FLAG in the message MESG. If optional argumen\n"
+"VALUE is @samp{#f}, the attribute is unset.")
 #define FUNC_NAME s_scm_mu_message_set_user_flag
 {
   mu_message_t msg;
@@ -808,13 +809,13 @@ SCM_DEFINE (scm_mu_message_set_user_flag, "mu-message-set-user-flag", 2, 1, 0,
 
 SCM_DEFINE (scm_mu_message_get_port, "mu-message-get-port", 2, 1, 0,
 	    (SCM MESG, SCM MODE, SCM FULL),
-	    "Returns a port associated with the given MESG. MODE is a string\n"
-	    "defining operation mode of the stream. It may contain any of the\n"
-	    "two characters: \"r\" for reading, \"w\" for writing.\n"
-	    "If optional FULL argument specified, it should be a boolean value.\n"
-	    "If it is #t then the returned port will allow access to any\n"
-	    "part of the message (including headers). If it is #f then the port\n"
-	    "accesses only the message body (the default).\n")
+"Returns a port associated with the given MESG. MODE is a string\n"
+"defining operation mode of the stream. It may contain any of the\n"
+"two characters: @samp{r} for reading, @samp{w} for writing.\n"
+"If optional argument FULL is specified, it should be a boolean value.\n"
+"If it is @samp{#t} then the returned port will allow access to any\n"
+"part of the message (including headers). If it is @code{#f} then the port\n"
+"accesses only the message body (the default).\n")
 #define FUNC_NAME s_scm_mu_message_get_port
 {
   mu_message_t msg;
@@ -879,7 +880,7 @@ SCM_DEFINE (scm_mu_message_get_body, "mu-message-get-body", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_multipart_p, "mu-message-multipart?", 1, 0, 0,
 	    (SCM MESG),
-	    "Returns #t if MESG is a multipart MIME message.")
+	    "Returns @code{#t} if MESG is a multipart @acronym{MIME} message.")
 #define FUNC_NAME s_scm_mu_message_multipart_p
 {
   mu_message_t msg;
@@ -894,8 +895,8 @@ SCM_DEFINE (scm_mu_message_multipart_p, "mu-message-multipart?", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_get_num_parts, "mu-message-get-num-parts", 1, 0, 0,
 	    (SCM MESG),
-	    "Returns number of parts in a multipart MIME message. Returns\n"
-            "#f if the argument is not a multipart message.")
+"Returns number of parts in a multipart @acronym{MIME} message. Returns\n"
+"@code{#f} if the argument is not a multipart message.")
 #define FUNC_NAME s_scm_mu_message_get_num_parts
 {
   mu_message_t msg;
@@ -920,7 +921,7 @@ SCM_DEFINE (scm_mu_message_get_num_parts, "mu-message-get-num-parts", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_message_get_part, "mu-message-get-part", 2, 0, 0,
 	    (SCM MESG, SCM PART),
-	    "Returns part number PART from a multipart MIME message.")
+"Returns part #PART from a multipart @acronym{MIME} message MESG.")
 #define FUNC_NAME s_scm_mu_message_get_part
 {
   mu_message_t msg, submsg;
@@ -947,9 +948,8 @@ SCM_DEFINE (scm_mu_message_get_part, "mu-message-get-part", 2, 0, 0,
 
 SCM_DEFINE (scm_mu_message_send, "mu-message-send", 1, 3, 0,
 	    (SCM MESG, SCM MAILER, SCM FROM, SCM TO),
-	    "Sends the message MESG. Optional MAILER overrides default\n"
-	    "mailer settings in mu-mailer.\n"
-	    "Optional FROM and TO are sender and recever addresses\n")
+"Sends the message MESG. Optional MAILER overrides default mailer settings\n"
+"in mu-mailer. Optional FROM and TO give sender and recever addresses.\n")
 #define FUNC_NAME s_scm_mu_message_send
 {
   const char *mailer_name;

@@ -90,7 +90,9 @@ mu_scm_is_mime (SCM scm)
 
 SCM_DEFINE (scm_mu_mime_create, "mu-mime-create", 0, 2, 0,
 	    (SCM FLAGS, SCM MESG),
-	    "Creates a new MIME object.")
+"Creates a new @acronym{MIME} object.  Both arguments are optional.\n"
+"FLAGS specifies the type of the object to create (@samp{0} is a reasonable\n"
+"value).  MESG gives the message to create the @acronym{MIME} object from.")
 #define FUNC_NAME s_scm_mu_mime_create
 {
   mu_message_t msg = NULL;
@@ -126,7 +128,7 @@ SCM_DEFINE (scm_mu_mime_create, "mu-mime-create", 0, 2, 0,
 
 SCM_DEFINE (scm_mu_mime_multipart_p, "mu-mime-multipart?", 1, 0, 0,
 	    (SCM MIME),
-	    "Returns #t if MIME is a multipart object.\n")
+"Returns @code{#t} if MIME is a multipart object.\n")
 #define FUNC_NAME s_scm_mu_mime_multipart_p
 {
   SCM_ASSERT (mu_scm_is_mime (MIME), MIME, SCM_ARG1, FUNC_NAME);
@@ -136,7 +138,7 @@ SCM_DEFINE (scm_mu_mime_multipart_p, "mu-mime-multipart?", 1, 0, 0,
 
 SCM_DEFINE (scm_mu_mime_get_num_parts, "mu-mime-get-num-parts", 1, 0, 0,
 	    (SCM MIME),
-	    "Returns number of parts in a MIME object.")
+"Returns number of parts in the @sc{mime} object MIME.")
 #define FUNC_NAME s_scm_mu_mime_get_num_parts
 {
   mu_mime_t mime;
@@ -154,22 +156,22 @@ SCM_DEFINE (scm_mu_mime_get_num_parts, "mu-mime-get-num-parts", 1, 0, 0,
 #undef FUNC_NAME
 
 SCM_DEFINE (scm_mu_mime_get_part, "mu-mime-get-part", 2, 0, 0,
-	    (SCM MIME, SCM PART),
-	    "Returns part number PART from a MIME object.")
+	    (SCM MIME, SCM NUM),
+	    "Returns NUMth part from the @sc{mime} object MIME.")
 #define FUNC_NAME s_scm_mu_mime_get_part
 {
   mu_message_t msg = NULL;
   int status;
   
   SCM_ASSERT (mu_scm_is_mime (MIME), MIME, SCM_ARG1, FUNC_NAME);
-  SCM_ASSERT (scm_is_integer (PART), PART, SCM_ARG2, FUNC_NAME);
+  SCM_ASSERT (scm_is_integer (NUM), NUM, SCM_ARG2, FUNC_NAME);
   
   status = mu_mime_get_part (mu_scm_mime_get (MIME),
-			     scm_to_int32 (PART), &msg);
+			     scm_to_int32 (NUM), &msg);
   if (status)
     mu_scm_error (FUNC_NAME, status,
 		  "Cannot get part ~A from MIME object ~A",
-		  scm_list_2 (PART, MIME));
+		  scm_list_2 (NUM, MIME));
   
   return mu_scm_message_create (MIME, msg);
 }
@@ -177,7 +179,7 @@ SCM_DEFINE (scm_mu_mime_get_part, "mu-mime-get-part", 2, 0, 0,
 
 SCM_DEFINE (scm_mu_mime_add_part, "mu-mime-add-part", 2, 0, 0,
 	    (SCM MIME, SCM MESG),
-	    "Adds MESG to the MIME object.")
+	    "Adds MESG to the @sc{mime} object MIME.")
 #define FUNC_NAME s_scm_mu_mime_add_part
 {
   mu_mime_t mime;
@@ -203,7 +205,7 @@ SCM_DEFINE (scm_mu_mime_add_part, "mu-mime-add-part", 2, 0, 0,
 
 SCM_DEFINE (scm_mu_mime_get_message, "mu-mime-get-message", 1, 0, 0,
 	    (SCM MIME),
-	    "Converts MIME object to a message.\n")
+	    "Converts @sc{mime} object MIME to a message.\n")
 #define FUNC_NAME s_scm_mu_mime_get_message
 {
   mu_mime_t mime;

@@ -114,16 +114,20 @@ register_format (const char *name)
 
 SCM_DEFINE (scm_mu_register_format, "mu-register-format", 0, 0, 1,
 	    (SCM REST),
-"Registers desired mailutils formats. Takes any number of arguments.\n"
-"Allowed arguments are:\n"
-"  \"mbox\"       Regular UNIX mbox format\n"
-"  \"mh\"         MH mailbox format\n"
-"  \"pop\"        POP mailbox format\n"
-"  \"imap\"       IMAP mailbox format\n"
-"  \"sendmail\"   sendmail mailer\n"
-"  \"smtp\"       smtp mailer\n"
+"Registers desired mailutils formats.  Any number of arguments can be given.\n"
+"Each argument must be one of the following strings:\n\n"
+"@multitable @columnfractions 0.3 0.6\n"
+"@headitem Argument @tab Meaning\n"
+"@item @samp{mbox}  @tab Regular UNIX mbox format\n"
+"@item @samp{mh}    @tab @acronym{MH} mailbox format\n"
+"@item @samp{maildir} @tab @i{Maildir} mailbox format\n"
+"@item @samp{pop}   @tab @acronym{POP} mailbox format\n"
+"@item @samp{imap}  @tab @acronym{IMAP} mailbox format\n"
+"@item @samp{sendmail} @tab @i{sendmail} mailer format\n"
+"@item @samp{smtp}  @tab @acronym{SMTP} mailer format\n"
+"@end multitable\n"
 "\n"
-"If called without arguments, registers all available formats\n")
+"If called without arguments, the function registers all available formats\n")
 #define FUNC_NAME s_scm_mu_register_format
 {
   int status;

@@ -20,11 +20,12 @@
 
 SCM_DEFINE (scm_mu_getpwuid, "mu-getpwuid", 1, 0, 0,
             (SCM USER),
-	    "Look up an entry in the user database. USER can be an integer,\n"
-	    "or a string, giving the behaviour of mu_get_auth_by_uid or mu_get_auth_by_name\n"
-	    "respectively.\n"
-	    "Returns a vector with fields corresponding to those of the mu_auth_data\n"
-	    "entry in question. If no matching entry was found, returns #f.\n")
+"Look up an entry in the user database. USER can be an integer,\n"
+"or a string, giving the behaviour of @code{mu_get_auth_by_uid} or\n"
+"@code{mu_get_auth_by_name} respectively.\n"
+"\n"
+"Returns a vector with fields corresponding to those of the @code{mu_auth_data}\n"
+"entry in question. If no matching entry was found, returns @code{#f}.\n")
 #define FUNC_NAME s_scm_mu_getpwuid
 {
   SCM result;