added hints for attachments

includes/messages/file.js

@@ -0,0 +1,8 @@
+let attachments = await browser.messages.listAttachments(messageId);
+for (let att of attachments) {
+    let file = await browser.messages.getAttachmentFile(
+        message.id,
+        att.partName
+    );
+    let content = await file.text();
+}

messages.rst

@@ -229,6 +229,16 @@ Lists all of the attachments of a message.
       :type: (integer)
 
 
+.. api-header::
+   :label: Return type (`Promise`_)
+
+
+   .. api-member::
+      :type: array of :ref:`messages.Attachment`
+
+
+   .. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
 .. api-header::
    :label: Required permissions
 
@@ -257,11 +267,26 @@ Gets the content of an attachment as a DOM ``File`` object.
       :type: (string)
 
 
+.. api-header::
+   :label: Return type (`Promise`_)
+
+
+   .. api-member::
+      :type: `File <https://developer.mozilla.org/en-US/docs/Web/API/File>`_
+
+
+   .. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
 .. api-header::
    :label: Required permissions
 
    - :permission:`messagesRead`
 
+The most simple way to get the content of an attachment is to use the ``text()`` method of the ``File`` object:
+
+.. literalinclude:: includes/messages/file.js
+  :language: JavaScript
+
 .. _messages.query:
 
 query(queryInfo)

overlay/messages.json

@@ -36,11 +36,21 @@
       },
       {
         "name": "listAttachments",
-        "added": "88"
+        "added": "88",
+        "returns": {
+          "type": "array",
+            "items": {
+              "$ref": "Attachment"
+            }
+        }
       },
       {
         "name": "getAttachmentFile",
-        "added": "88"
+        "added": "88",
+        "hints": "The most simple way to get the content of an attachment is to use the ``text()`` method of the ``File`` object:<literalinclude>includes/messages/file.js<lang>JavaScript</lang></literalinclude>",
+        "returns": {
+          "$ref": "extensionTypes.File"
+        }
       },
       {
         "name": "query",

update-docs.py

@@ -112,6 +112,8 @@ def get_type(obj, name):
 
 def link_ref(ref):
     global additional_type_used
+    if ref == "extensionTypes.File":
+        return "`File <https://developer.mozilla.org/en-US/docs/Web/API/File>`_"
     if ref == "extensionTypes.Date":
         return "`Date <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date>`_"
     if ref == "runtime.Port":
@@ -161,6 +163,12 @@ def format_changes(obj, inline = False):
                 lines.extend(api_header("Changes in Thunderbird " + k, api_member(name=replace_code(v))))
     return lines
 
+def format_hints(obj):
+    lines = []
+    if "hints" in obj:
+        lines.extend(replace_code(obj['hints']).split("\n"))
+    return lines
+
 def get_api_member_parts(name, value):
     parts = {
         "name" : "",
@@ -525,6 +533,11 @@ def format_namespace(manifest, namespace):
             lines.extend(format_permissions(function, namespace))
             #lines.extend(enum_lines)
 
+            if "hints" in function:
+                lines.extend(format_hints(function))
+
+
+
 
     if "events" in namespace:
         lines.append("")