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
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.sandboxfor a SSCCE.I found that it was not very clear from the
Browser.elementorBrowser.sandboxdocs 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
nodefield, 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:
Browserdocs.Thanks!
Coury