More thorough documancy for Platform.program because it's complex and… #757

Pilatch · Nov 21, 2016

… confusing, and other sources of information don't paint a clear enough picture for beginners.

I spent a long time trying to figure this out, and nothing official was helping. This is documentation from a beginner, for beginners. It spells out what's going on in more gory detail to spare others pain of integrating Elm into arbitrary JavaScript.

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 · Nov 21, 2016

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.

richardhaven · Nov 21, 2016

richardhaven reviewed Nov 21, 2016

View changes

"The commad should be generated by passing data through an outbound port."
This is a bit confusing for beginners itself. Also, note the typo.
Perhaps just repeat the bit from init about it's usually Cmd.none

Working on making it better. I should have an update soon.

Pilatch · Nov 21, 2016

Working on making it better. I should have an update soon.

How do I get this thing to re-run the tests without making another commit?

Pilatch · Nov 21, 2016

How do I get this thing to re-run the tests without making another commit?

How do I get this thing to re-run the tests without making another commit?

An owner of this repo can restart it, but as a user I think the only way is to just close then re-open this pull request (not open a new one, just re-open the same old one).

OvermindDL1 · Nov 21, 2016

How do I get this thing to re-run the tests without making another commit?

An owner of this repo can restart it, but as a user I think the only way is to just close then re-open this pull request (not open a new one, just re-open the same old one).

Cool. I'll try that.

Pilatch · Nov 21, 2016

Cool. I'll try that.

Neato. It's doing it.

Pilatch · Nov 21, 2016

Neato. It's doing it.

Trying one last time just in case the test failure is intermittent.

Pilatch · Nov 21, 2016

Trying one last time just in case the test failure is intermittent.

I am a detailed documentation editor. I'm happy to review stuff

richardhaven · Nov 21, 2016

I am a detailed documentation editor. I'm happy to review stuff

Yea, a review would be great!

Pilatch · Nov 21, 2016

Yea, a review would be great!

richardhaven · Nov 21, 2016

richardhaven reviewed Nov 21, 2016

View changes

Maybe documenting the plumbing and tips on how to use subscriptions is too much

richardhaven · Nov 21, 2016

src/Platform.elm

+
+The second argument, `update` is a function that takes these two arguments:
+
+1. A message from the outside world, that has the information your code will act upon.


remove comma before "that"

richardhaven · Nov 21, 2016

src/Platform.elm

+
+1. A message from the outside world, that has the information your code will act upon.
+Usually this is a `Msg` type that you specify, (a constructor), which takes a record type
+matching the data coming from an incoming port. Unpack that data with `case` ... `of`.


give a simple example of the Msg object (e.g. how to create one)

How about a link to here? https://www.elm-tutorial.org/en/02-elm-arch/03-messages.html

richardhaven · Nov 21, 2016

src/Platform.elm

+Usually this is a `Msg` type that you specify, (a constructor), which takes a record type
+matching the data coming from an incoming port. Unpack that data with `case` ... `of`.
+
+2. The current state of your program's model, as maintained by the Elm runtime.


"model" is a variable in this application. It's not really "maintained by the Elm runtime

I just deleted the back half of that sentence.

richardhaven · Nov 21, 2016

src/Platform.elm

+2. The current state of your program's model, as maintained by the Elm runtime.
+
+The `update` function must return a [Tuple](Tuple)
+containing the modified form of your program's model, and a command.


The "command" gets fed back into the update unless it is Cmd.none

This does not appear to be true. I've been debugging a program here - https://github.com/Pilatch/elm-port-program-examples/blob/master/greeter/Greet.elm - and can't find any evidence to show that update is getting called multiple times when I supply a non-none command in the second half of the tuple that's returned from update.

Here I have the result of debugging the result of a Cmd.map:

{ type = "map", tagger = <function>, tree = { type = "leaf", home = "greet", value = "jomomma" } }

Here is the result of debugging Cmd.none:

{ type = "node", branches = [] }

They are significantly different, yet in both cases the update function is not run again, with the supplied message coming from Cmd.map.

richardhaven · Nov 21, 2016

src/Platform.elm

+    let newModel =
+            model.greetings + 1 |> Model
+
+        greeting = case msg of


single-case is a bad code example. Use "if" to check for a single case

How do you extract a message's payload with an if statement?

richardhaven · Nov 21, 2016

src/Platform.elm

+
+The `update` function must return a [Tuple](Tuple)
+containing the modified form of your program's model, and a command.
+Generate that command by passing data to an outbound port. The data type


The command can be created by passing data to a port, but that is a specific (if common) case. Separate that from this quick overview

The code sample that follows that text illustrates that common use case, so I think it's safe to just delete the text in question.

Thought about it. The common use case is important in the demystification process. Had I deleted text as I commented above, then my documentation would be no better than the type annotations.

Nevertheless I have taken the suggestion into account, reworded, and separated the common use case into a new paragraph.

richardhaven · Nov 21, 2016

src/Platform.elm

+type Msg = Name String
+
+type alias Model = { greetings : Int }
+


where is model = Model(0)

If I include that, then I have an init function, and may as well have a subscriptions function, then may as well have the Process.program call for completeness.

richardhaven · Nov 21, 2016

src/Platform.elm

+
+type alias Model =
+    { numChanges : Int}
+-- Assume the update function increments `numChanges`.


where is model = Model(0) ?

Went the completeness route, and put one big code sample in there.

Regarding plumbing and tips for subscriptions, I'll have to look into when/how frequently subscriptions is called, then I'll better reform that section.

Pilatch · Nov 22, 2016

Regarding plumbing and tips for subscriptions, I'll have to look into when/how frequently subscriptions is called, then I'll better reform that section.

More thorough documancy for Platform.program because it's complex and…
… confusing, and other sources of information don't paint a clear enough picture for beginners.

4a701a5

lukewestby added the docs label Nov 21, 2016

Fix typo. Uses more, and relative links. More explanation and a code …
…sample for `update`.

151bfb7

Pilatch closed this Nov 21, 2016

Pilatch reopened this Nov 21, 2016

Pilatch closed this Nov 21, 2016

Pilatch reopened this Nov 21, 2016

Refactor documentation in response to comments in pull request.

6deb917

Refined subscriptions documancy. Noted when it's called.

58378db

Pilatch closed this Dec 15, 2016

Pilatch reopened this Dec 15, 2016

elm/core

Join GitHub today

More thorough documancy for Platform.program because it's complex and… #757

Conversation

Pilatch commented Nov 21, 2016

This comment has been minimized.

process-bot commented Nov 21, 2016

lukewestby added the docs label Nov 21, 2016

richardhaven reviewed Nov 21, 2016 View changes

This comment has been minimized.

Pilatch commented Nov 21, 2016

This comment has been minimized.

Pilatch commented Nov 21, 2016

This comment has been minimized.

OvermindDL1 commented Nov 21, 2016

This comment has been minimized.

Pilatch commented Nov 21, 2016

Pilatch closed this Nov 21, 2016

Pilatch reopened this Nov 21, 2016

This comment has been minimized.

Pilatch commented Nov 21, 2016

This comment has been minimized.

Pilatch commented Nov 21, 2016

Pilatch closed this Nov 21, 2016

Pilatch reopened this Nov 21, 2016

This comment has been minimized.

richardhaven commented Nov 21, 2016

This comment has been minimized.

Pilatch commented Nov 21, 2016

richardhaven reviewed Nov 21, 2016 View changes

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Pilatch Nov 22, 2016 • edited Edited 1 time Pilatch edited Nov 22, 2016 (most recent)

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Pilatch commented Nov 22, 2016

Pilatch closed this Dec 15, 2016

Pilatch reopened this Dec 15, 2016

richardhaven reviewed Nov 21, 2016

View changes

richardhaven reviewed Nov 21, 2016

View changes

Pilatch Nov 22, 2016 •

edited

Edited 1 time

Pilatch edited Nov 22, 2016 (most recent)