diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2006-06-15 13:30:41 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2006-06-15 13:30:41 +0000 |
commit | 3bd03f85964a48e82d2c488cc5dc3c36c6dcab2a (patch) | |
tree | 3b407882c2a85ed1c42bb24f0a9b0f96dba003e2 | |
parent | 4f7a5cfb3f41bd73e483e4196d590fb45223638f (diff) | |
download | mailutils-3bd03f85964a48e82d2c488cc5dc3c36c6dcab2a.tar.gz mailutils-3bd03f85964a48e82d2c488cc5dc3c36c6dcab2a.tar.bz2 |
Update docstrings
-rw-r--r-- | libmu_scm/mu_address.c | 16 | ||||
-rw-r--r-- | libmu_scm/mu_logger.c | 7 | ||||
-rw-r--r-- | libmu_scm/mu_mailbox.c | 73 | ||||
-rw-r--r-- | libmu_scm/mu_message.c | 82 | ||||
-rw-r--r-- | libmu_scm/mu_mime.c | 22 | ||||
-rw-r--r-- | libmu_scm/mu_scm.c | 22 | ||||
-rw-r--r-- | libmu_scm/mu_util.c | 11 |
7 files changed, 122 insertions, 111 deletions
diff --git a/libmu_scm/mu_address.c b/libmu_scm/mu_address.c index 72ed64f8b..f2d691d6b 100644 --- a/libmu_scm/mu_address.c +++ b/libmu_scm/mu_address.c @@ -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; diff --git a/libmu_scm/mu_logger.c b/libmu_scm/mu_logger.c index 23604af52..abb57984d 100644 --- a/libmu_scm/mu_logger.c +++ b/libmu_scm/mu_logger.c @@ -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 (); diff --git a/libmu_scm/mu_mailbox.c b/libmu_scm/mu_mailbox.c index 8e5a623a5..c4168754e 100644 --- a/libmu_scm/mu_mailbox.c +++ b/libmu_scm/mu_mailbox.c @@ -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; diff --git a/libmu_scm/mu_message.c b/libmu_scm/mu_message.c index 7732e0b80..7c3f98a8d 100644 --- a/libmu_scm/mu_message.c +++ b/libmu_scm/mu_message.c @@ -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; diff --git a/libmu_scm/mu_mime.c b/libmu_scm/mu_mime.c index 84923face..125db7353 100644 --- a/libmu_scm/mu_mime.c +++ b/libmu_scm/mu_mime.c @@ -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; diff --git a/libmu_scm/mu_scm.c b/libmu_scm/mu_scm.c index b5e8c48c8..066b5f2a9 100644 --- a/libmu_scm/mu_scm.c +++ b/libmu_scm/mu_scm.c @@ -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; diff --git a/libmu_scm/mu_util.c b/libmu_scm/mu_util.c index 995ad96c4..8373243b3 100644 --- a/libmu_scm/mu_util.c +++ b/libmu_scm/mu_util.c @@ -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; |