I appreciate how much effort and focus the Elm community devotes to clear & thorough documentation. In an effort to continue improving the docs, I'll go over an experience I recently had trying to use Browser.sandbox for a SSCCE.
I found that it was not very clear from the Browser.element or Browser.sandbox docs how to initialize them within JS.
I spent quite a bit of time pouring over the package docs, elm guide, and elm guide examples to no avail.
I eventually happened upon https://guide.elm-lang.org/interop/ , which shows the use of the node field, but it's not clear when this field is relevant wrt sandbox, element, document, application. I also found https://guide.elm-lang.org/webapps/, but this only shows how to init a document.
Potential ways to ameliorate this confusion:
Include js snipptes in the Browser docs.
Include js/html snippets in the guides examples instead of only pure Elm.
Include something like the table below as a quick and clear reference in the Browser docs and Elm guide (with help from @Janiczek).
+----------------------+-------------------+------------------------+
| entry point js param | uses `node` field | supports `flags` field |
+----------------------+-------------------+------------------------+
| Platform.worker | no | yes |
+----------------------+-------------------+------------------------+
| Browser.sandbox | yes | no |
+----------------------+-------------------+------------------------+
| Browser.element | yes | yes |
+----------------------+-------------------+------------------------+
| Browser.document | no | yes |
+----------------------+-------------------+------------------------+
| Browser.application | no | yes |
+----------------------+-------------------+------------------------+
I appreciate how much effort and focus the Elm community devotes to clear & thorough documentation. In an effort to continue improving the docs, I'll go over an experience I recently had trying to use
Browser.sandbox
for a SSCCE.I found that it was not very clear from the
Browser.element
orBrowser.sandbox
docs how to initialize them within JS.I spent quite a bit of time pouring over the package docs, elm guide, and elm guide examples to no avail.
I eventually happened upon https://guide.elm-lang.org/interop/ , which shows the use of the
node
field, but it's not clear when this field is relevant wrtsandbox, element, document, application
. I also found https://guide.elm-lang.org/webapps/, but this only shows how to init adocument
.Potential ways to ameliorate this confusion:
Browser
docs.Thanks! Coury