[epiphany/pgriffis/web-extension/readme-update: 2/2] WebExtensions: Update readme with up to date API information.

[Marge Bot <marge-bot src gnome org>]

commit 5164327c73cb97309d7d1652ea025d7824b1b5e2
Author: Patrick Griffis <pgriffis igalia com>
Date:   Thu Jun 23 11:53:02 2022 -0500

    WebExtensions: Update readme with up to date API information.
    
    Part-of: <https://gitlab.gnome.org/GNOME/epiphany/-/merge_requests/1153>

 src/webextension/README.md | 176 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 158 insertions(+), 18 deletions(-)
---
diff --git a/src/webextension/README.md b/src/webextension/README.md
index 74dae0964..3bfc12a76 100644
--- a/src/webextension/README.md
+++ b/src/webextension/README.md
@@ -17,24 +17,164 @@ You can track issues here: https://gitlab.gnome.org/GNOME/epiphany/-/issues?labe
     - initial content_scripts
     - initial background page
     - initial background scripts
-- WebExtension API:
-    - i18n:
-        - getMessage
-        - getUILanguage
-    - runtime:
-        - sendMessage
-        - onMessage.addListener
-    - notifications:
-        - create
-    - pageAction:
-        - setIcon
-        - setTitle
-        - show
-    - getTitle
-    - tabs:
-        - insertCSS
-        - removeCSS
-        - initial query
+
+### WebExtension JavaScript APIs
+
+All of these APIs follow Firefox in behavior. They have the entrypoint of `browser` and return a `Promise`.
+
+However just like Firefox we try to retain compatibility with Chrome and the `chrome` entry point works and 
if the last argument is a function it is treated as a callback with `lastError` set appropriately.
+
+#### alarms
+
+The alarms API is fully implemented.
+
+- clear()
+- clearAll()
+- create()
+- get()
+- getAll()
+- onAlarm
+
+#### browserAction
+
+- onClicked
+
+#### cookies
+
+Limitations:
+
+- Epiphany only has a single cookieStore and all APIs will always use it.
+- Filtering by firstParty domains isn't supported.
+- You cannot request all cookies, a domain must be given.
+- onChanged is only a stub and will never be called.
+
+APIs:
+
+- get()
+- getAll()
+- getAllCookieStores()
+- set()
+- remove()
+- onChanged
+
+#### downloads
+
+Limitations:
+
+- Unlike other browsers downloadIds are not persistent across sessions. Downloads are always "incognito" as 
they are always lost.
+- Pausing/Resuming downloads is not supported.
+- Returned download lists are not sorted by "orderBy" (TODO)
+
+APIs:
+
+- cancel()
+- download()
+- erase()
+- open()
+- removeFile()
+- show()
+- showDefaultFolder()
+- search()
+- onCreated
+- onChanged
+- onErased
+
+#### extension
+
+- getViews()
+- getBackgroundPage()
+- getURL()
+
+#### i18n
+
+This is only partially implemented, see https://gitlab.gnome.org/GNOME/epiphany/-/issues/1791
+
+- getMessage()
+- getUILanguage()
+
+#### runtime
+
+This is partially implemented. Message passing including replies works including from Content Scripts.
+
+- getBackgroundPage()
+- getBrowserInfo()
+- getPlatformInfo()
+- getURL()
+- openOptionsPage()
+- sendMessage()
+- onMessage
+- lastError
+
+#### notifications
+
+Limitations:
+
+- Icons are not supported.
+- We can't track when notificaions are shown or dismissed.
+
+APIs:
+
+- create()
+- clear()
+- getAll()
+- update()
+- onClicked
+- onButtonClicked
+
+#### pageAction
+
+- setIcon()
+- setTitle()
+- getTitle()
+- show()
+- onClicked
+
+#### storage
+
+Limitations:
+
+- Sync storage isn't implemented but possible as Epiphany uses Firefox Sync.
+- onChanged isn't implemented (TODO)
+
+APIs:
+
+- local.set()
+- local.get()
+- local.remove()
+- local.clear()
+
+#### tabs
+
+Limitations:
+
+- Some of these APIs are supposed to return after the page is loaded but return immediately. (TODO)
+- None of the events are supported yet. (TODO)
+
+APIs:
+
+- create()
+- query()
+- insertCSS()
+- remove()
+- removeCSS()
+- get()
+- getZoom()
+- setZoom()
+- update()
+- reload()
+- executeScript()
+- sendMessage()
+
+#### windows
+
+- get()
+- getCurrent()
+- getLastFocused()
+- getAll()
+- create()
+- remove()
+- onCreated
+- onRemoved
 
 ### Tested extensions