Description
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 |
+----------------------+-------------------+------------------------+
- All of the above
- None of the above and something better?
Thanks!
Coury