Add documentation for (!) in Platform.Cmd

[cobalamin]

What (!) is or does is such a common source of confusion and thus a very common question in the Elm Slack, especially in #beginners. It's very commonly used in code in the wild, especially the model ! [] form.

There's no way for newcomers to figure this out on their own, as there is no comprehensive explanation in the guide on this – and worse, no documentation on the function in the package. So I wrote some. I hope it works 😄

[process-bot]

Thanks for the pull request! Make sure it satisfies this checklist. My human colleagues will appreciate it!

Here is what to expect next, and if anyone wants to comment, keep these things in mind.

[process-bot]

Thanks for the pull request! Make sure it satisfies this checklist. My human colleagues will appreciate it!

Here is what to expect next, and if anyone wants to comment, keep these things in mind.

[jvoigtlaender]

I'm all for adding documentation.

One comment, though: This specific construct is explained in the FAQ for Learners linked to from http://elm-lang.org/docs. Here: http://faq.elm-community.org/17.html#what-is-this---construct-in-the-code.

What is wrong with the FAQ that people "in the Elm Slack, especially in #beginners" do not find it, or do not think of looking there?

[jvoigtlaender]

I'm all for adding documentation.

One comment, though: This specific construct is explained in the FAQ for Learners linked to from http://elm-lang.org/docs. Here: http://faq.elm-community.org/17.html#what-is-this---construct-in-the-code.

What is wrong with the FAQ that people "in the Elm Slack, especially in #beginners" do not find it, or do not think of looking there?

[jvoigtlaender]

Oh, and the way you included code samples in the docs is not the way to do it. Please look at examples in other source files, e.g., src/Maybe.elm.

[jvoigtlaender]

Oh, and the way you included code samples in the docs is not the way to do it. Please look at examples in other source files, e.g., src/Maybe.elm.

[cobalamin]

Fair point!

Nothing specific wrong with the FAQ, but the only way I stumbled on that myself was when I had already worked through the guide and some other materials, and went on to check everything at elm-lang.org/docs out of curiosity. It's the last bullet point and it's not bolded, so it's fairly easy to miss, even there.

Coming from doing the guide, checking the package docs seems like a more straightforward progression for me. And maybe some newcomers won't even think that this is a FAQ, but that they're just missing something simple.

Oops, sorry about the documentation example format, I'll rectify that. Can I even put that into this PR, or do I need to close and open a new one?

[cobalamin]

Fair point!

Nothing specific wrong with the FAQ, but the only way I stumbled on that myself was when I had already worked through the guide and some other materials, and went on to check everything at elm-lang.org/docs out of curiosity. It's the last bullet point and it's not bolded, so it's fairly easy to miss, even there.

Coming from doing the guide, checking the package docs seems like a more straightforward progression for me. And maybe some newcomers won't even think that this is a FAQ, but that they're just missing something simple.

Oops, sorry about the documentation example format, I'll rectify that. Can I even put that into this PR, or do I need to close and open a new one?

[jvoigtlaender]

Can I even put that into this PR, or do I need to close and open a new one?

You can add commits to a PR. You can also squash commits inside a PR until it is merged. Force-pushing to PRs is frequently done by people around here.

[jvoigtlaender]

Can I even put that into this PR, or do I need to close and open a new one?

You can add commits to a PR. You can also squash commits inside a PR until it is merged. Force-pushing to PRs is frequently done by people around here.

[cobalamin]

Alright, apparently that worked!

[cobalamin]

Alright, apparently that worked!

[cobalamin]

Further digression on the FAQ point: I just noticed the link you shared is actually only in the subsection for specific 0.17 upgrading questions. It's linked with this text:

See also the Elm 0.17 FAQ about upgrading to Elm 0.17.

As a newcomer right now I would pretty much never check this – "I've not used any version before this current one, so why check the upgrading notes?"

So thanks for the link, I'll share it with people in the Slack, but I think it's hard to find on your own for someone new.

[cobalamin]

Further digression on the FAQ point: I just noticed the link you shared is actually only in the subsection for specific 0.17 upgrading questions. It's linked with this text:

See also the Elm 0.17 FAQ about upgrading to Elm 0.17.

As a newcomer right now I would pretty much never check this – "I've not used any version before this current one, so why check the upgrading notes?"

So thanks for the link, I'll share it with people in the Slack, but I think it's hard to find on your own for someone new.

[jvoigtlaender]

Yes, you are right, and I also think that the FAQ needs restructuring as Elm 0.16 fades into history.

[jvoigtlaender]

Yes, you are right, and I also think that the FAQ needs restructuring as Elm 0.16 fades into history.

[evancz]

Planning on dropping this operator. If it is not dropped in the final release, it will be added back with documentation.

[evancz]

Planning on dropping this operator. If it is not dropped in the final release, it will be added back with documentation.

[nathanfox]

I personally like and extensively use the ! operator. Granted I can create my own if it is dropped in a future release, but I'd vote to keep it.

[nathanfox]

I personally like and extensively use the ! operator. Granted I can create my own if it is dropped in a future release, but I'd vote to keep it.