Commit 6580b02c authored by rswindell's avatar rswindell
Browse files

Attempt to clarify all this MsgBase.get...(by_offset, number_or_offset_or_id_header)

confusion: You should not pass both a message number *and* a message header to the
retrieval methods that support referring to a message by either (number/offset, id
or header).
parent a07ad8e9
......@@ -2801,7 +2801,7 @@ static jsSyncMethodSpec js_msgbase_functions[] = {
,JSDOCSTR("close message base (if open)")
,310
},
{"get_msg_header", js_get_msg_header, 4, JSTYPE_OBJECT, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_id [,expand_fields=<tt>true</tt>] [,include_votes=<tt>false</tt>]")
{"get_msg_header", js_get_msg_header, 4, JSTYPE_OBJECT, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_offset_or_id [,expand_fields=<tt>true</tt>] [,include_votes=<tt>false</tt>]")
,JSDOCSTR("returns a specific message header, <i>null</i> on failure. "
"<br><i>New in v3.12:</i> Pass <i>false</i> for the <i>expand_fields</i> argument (default: <i>true</i>) "
"if you will be re-writing the header later with <i>put_msg_header()</i>")
......@@ -2813,23 +2813,26 @@ static jsSyncMethodSpec js_msgbase_functions[] = {
"Vote messages are excluded by default.")
,316
},
{"put_msg_header", js_put_msg_header, 2, JSTYPE_BOOLEAN, JSDOCSTR("[by_offset=<tt>false</tt>,] number, object header")
{"put_msg_header", js_put_msg_header, 2, JSTYPE_BOOLEAN, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_offset, object header")
,JSDOCSTR("modify an existing message header")
,310
},
{"get_msg_body", js_get_msg_body, 2, JSTYPE_STRING, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_id [, message_header] [,strip_ctrl_a=<tt>false</tt>] "
{"get_msg_body", js_get_msg_body, 2, JSTYPE_STRING, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_offset_or_id_or_header [,strip_ctrl_a=<tt>false</tt>] "
"[,rfc822_encoded=<tt>false</tt>] [,include_tails=<tt>true</tt>] [,plain_text=<tt>false</tt>]")
,JSDOCSTR("returns the entire body text of a specific message as a single String, <i>null</i> on failure. "
"The default behavior is to leave Ctrl-A codes intact, perform no RFC-822 encoding, and to include tails (if any) in the "
"returned body text. When <i>plain_text</i> is true, only the first plain-text portion of a multi-part MIME encoded message body is returned."
"returned body text. When <i>plain_text</i> is true, only the first plain-text portion of a multi-part MIME encoded message body is returned. "
"The first argument (following the optional <i>by_offset</i> boolean) must be either a number (message number or index-offset), string (message-ID), or object (message header). "
"The <i>by_offfset</i> (<tt>true</tt>) argument should only be passed when the argument following it is the numeric index-offset of the message to be "
"retrieved. By default (<i>by_offset</i>=<tt>false</tt>), a numeric argument would be interpreted as the message <i>number</i> to be retrieved. "
)
,310
},
{"get_msg_tail", js_get_msg_tail, 2, JSTYPE_STRING, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_id [, message_header] [,strip_ctrl_a]=<tt>false</tt>")
{"get_msg_tail", js_get_msg_tail, 2, JSTYPE_STRING, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_offset_or_id_or_header [,strip_ctrl_a]=<tt>false</tt>")
,JSDOCSTR("returns the tail text of a specific message, <i>null</i> on failure")
,310
},
{"get_msg_index", js_get_msg_index, 3, JSTYPE_OBJECT, JSDOCSTR("[by_offset=<tt>false</tt>,] number, [include_votes=<tt>false</tt>]")
{"get_msg_index", js_get_msg_index, 3, JSTYPE_OBJECT, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_offset, [include_votes=<tt>false</tt>]")
,JSDOCSTR("returns a specific message index, <i>null</i> on failure. "
"The index object will contain the following properties:<br>"
"<table>"
......@@ -2852,7 +2855,7 @@ static jsSyncMethodSpec js_msgbase_functions[] = {
)
,311
},
{"remove_msg", js_remove_msg, 2, JSTYPE_BOOLEAN, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_id")
{"remove_msg", js_remove_msg, 2, JSTYPE_BOOLEAN, JSDOCSTR("[by_offset=<tt>false</tt>,] number_or_offset_or_id")
,JSDOCSTR("mark message for deletion")
,311
},
......@@ -3058,7 +3061,14 @@ js_msgbase_constructor(JSContext *cx, uintN argc, jsval *arglist)
js_DescribeSyncObject(cx,obj,"Class used for accessing message bases",310);
js_DescribeSyncConstructor(cx,obj,"To create a new MsgBase object: "
"<tt>var msgbase = new MsgBase('<i>code</i>')</tt><br>"
"where <i>code</i> is a sub-board internal code, or <tt>mail</tt> for the e-mail message base");
"where <i>code</i> is a sub-board internal code, or <tt>mail</tt> for the e-mail message base."
"<br>"
"The MsgBase retrieval methods that accept a <tt>by_offset</tt> argument as their optional first boolean argument "
"will interpret the following <i>number</i> argument as either a 1-based unique message number (by_offset=<tt>false</tt>) "
"or a 0-based message index-offset (by_offset=<tt>true</tt>). Retrieving messages by offset is faster than by number or "
"message-id (string). Passing an existing message header to the retrieval methods that support it (e.g. <tt>get_msg_body()</tt>) "
"is the even faster. "
);
js_CreateArrayOfStrings(cx, obj, "_property_desc_list", msgbase_prop_desc, JSPROP_READONLY);
#endif
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment