+# After this function returns, the filename of the generated message
+# is available as $gen_msg_filename and the message ID is available as
+# $gen_msg_id .
+#
+# This function supports named parameters with the bash syntax for
+# assigning a value to an associative array ([name]=value). The
+# supported parameters are:
+#
+# [dir]=directory/of/choice
+#
+# Generate the message in directory 'directory/of/choice' within
+# the mail store. The directory will be created if necessary.
+#
+# [body]=text
+#
+# Text to use as the body of the email message
+#
+# '[from]="Some User <user@example.com>"'
+# '[to]="Some User <user@example.com>"'
+# '[subject]="Subject of email message"'
+# '[date]="RFC 822 Date"'
+#
+# Values for email headers. If not provided, default values will
+# be generated instead.
+#
+# '[cc]="Some User <user@example.com>"'
+# [in-reply-to]=<message-id>
+#
+# Additional values for email headers. If these are not provided
+# then the relevant headers will simply not appear in the
+# message.