Clarify which signal is discarded in Signal.merge example

[eeue56]

No description provided.

[rgrempel]

One thing I've noticed in Elm documentation generally is that the documentation sometimes (as in this case) refers to the names of variables, but when the documentation is presented on the web site, the names of variables don't actually show up. Now, sometimes you can tell from the types, but in this case the types are the same. And, in this case I suppose you could deduce what "left" and "right" mean, but sometimes it is more difficult than that.

So, this PR solves the general problem by being more explicit in the documentation -- that is, being explicit about which parameter is "left" and "right".

It might make sense to change the way the package web-site is generated, to solve the problem more generally, by showing the variable names in documentation. However, I guess that functions don't always
name their variables (if written in point-free form). So, it might be tricky -- perhaps being more explicit in the documentation is the best practical solution.

[rgrempel]

One thing I've noticed in Elm documentation generally is that the documentation sometimes (as in this case) refers to the names of variables, but when the documentation is presented on the web site, the names of variables don't actually show up. Now, sometimes you can tell from the types, but in this case the types are the same. And, in this case I suppose you could deduce what "left" and "right" mean, but sometimes it is more difficult than that.

So, this PR solves the general problem by being more explicit in the documentation -- that is, being explicit about which parameter is "left" and "right".

It might make sense to change the way the package web-site is generated, to solve the problem more generally, by showing the variable names in documentation. However, I guess that functions don't always
name their variables (if written in point-free form). So, it might be tricky -- perhaps being more explicit in the documentation is the best practical solution.

[eeue56]

I would agree with that - the people coming from Haskell backgrounds are usually fine guessing how something works from the type signature, but for those from JS/web dev backgrounds, having the names there is important.

[eeue56]

I would agree with that - the people coming from Haskell backgrounds are usually fine guessing how something works from the type signature, but for those from JS/web dev backgrounds, having the names there is important.

[jvoigtlaender]

Can you provide an example of the general issue of using invisible parameter names in the documentation? In the specific example here, I cannot see the issue. The use of "left" and "right" in the documentation here is not a reference to the parameter names left/right, but to the natural language concepts "left"/"right". So I don't think the extra sentence is necessary.

If the extra sentence is to be added, then the "Mouse.position" should be put into backticks, so that it will show up properly type-set on the package documentation page.

[jvoigtlaender]

Can you provide an example of the general issue of using invisible parameter names in the documentation? In the specific example here, I cannot see the issue. The use of "left" and "right" in the documentation here is not a reference to the parameter names left/right, but to the natural language concepts "left"/"right". So I don't think the extra sentence is necessary.

If the extra sentence is to be added, then the "Mouse.position" should be put into backticks, so that it will show up properly type-set on the package documentation page.

[eeue56]

The issue here came up yesterday on IRC - someone didn't understand which argument was to be considered right. When talking about function arguments, normal language used to refer is instead "nth argument" rather than left or right. Signal.merge could take the 1st param as being right, and the 2nd param as left - in the current documentation, it's ambiguous. In terms of Signals, left and right makes sense, if you have seen the relevant visualizations or read the research. By making it explicitly clear which argument is referred to here, people learning Elm can understand how to use Signal.merge without needing the complete background.

[eeue56]

The issue here came up yesterday on IRC - someone didn't understand which argument was to be considered right. When talking about function arguments, normal language used to refer is instead "nth argument" rather than left or right. Signal.merge could take the 1st param as being right, and the 2nd param as left - in the current documentation, it's ambiguous. In terms of Signals, left and right makes sense, if you have seen the relevant visualizations or read the research. By making it explicitly clear which argument is referred to here, people learning Elm can understand how to use Signal.merge without needing the complete background.

[jvoigtlaender]

Interesting. I would never have thought that in either of merge x y or xmergey there could be any doubt which is left and which is right. The text as written should make clear which of x and y is considered the left one? Just as for foldl and foldr it is clear what the "left" and what the "right" end are of a list [1,2,3]? (In particular, I don't need to assume someone having specific signal visualizations in mind, or read the research, to make it seem clear that x is the left and y is the right parameter in both expressions as written above.)

Anyway, you do mention evidence that someone was confused. I'll leave it to Evan to decide whether to merge this for the documentation.

Still, I'm actually more intrigued by @rgrempel's comment that generally some documentation snippets work only based on the assumption that the reader knows how the function parameters are called in the source code. And still, I don't see the current instance as an example for this. Here, the understanding the documentation assumed as given was not "you should know what I mean by left and right, because it's how I called the function parameters", but instead "you should know what I mean by left and right, because we are talking about function application expressions, and these are layed out as text, and there you can see which is the left and which is the right operand".

[jvoigtlaender]

Interesting. I would never have thought that in either of merge x y or xmergey there could be any doubt which is left and which is right. The text as written should make clear which of x and y is considered the left one? Just as for foldl and foldr it is clear what the "left" and what the "right" end are of a list [1,2,3]? (In particular, I don't need to assume someone having specific signal visualizations in mind, or read the research, to make it seem clear that x is the left and y is the right parameter in both expressions as written above.)

Anyway, you do mention evidence that someone was confused. I'll leave it to Evan to decide whether to merge this for the documentation.

Still, I'm actually more intrigued by @rgrempel's comment that generally some documentation snippets work only based on the assumption that the reader knows how the function parameters are called in the source code. And still, I don't see the current instance as an example for this. Here, the understanding the documentation assumed as given was not "you should know what I mean by left and right, because it's how I called the function parameters", but instead "you should know what I mean by left and right, because we are talking about function application expressions, and these are layed out as text, and there you can see which is the left and which is the right operand".

[eeue56]

The text as written should make clear which of x and y is considered the left one?

I personally didn't have any issues understanding it, but when they mentioned being confused by it, I can certainly see where they're coming from - but that's just because usually I would refer to arguments as nth argument. In this case, I would think that using nth argument would have the potential to be equally confusing, especially if you start talking about the 1st signal or the 2nd signal being dropped - it would imply an order to something unordered (signals coming in at the same time).

With an infix example, left and right certainly are a lot more obvious - I guess the difference here is that because the arguments are on different lines, it may lead to a different interpretation. The reader may left feeling like they are expected to know which is left and right in the implementation, as the chap on IRC did yesterday. But I don't know if there's a right answer here or not, really.

As to @rgrempel's point, the one that popped up in my head as a good example is the documentation for Graphics.Collage.collage, which a student complained to me about.

A collage is a collection of 2D forms. There are no strict positioning relationships between forms, so you are free to do all kinds of 2D graphics.

They were used to defining things as height, width, and thus were confused when their collage didn't come out as expected - simply naming the arguments in the documentation would've prevented their confusion. Perhaps adding width, height to the docs would've made it more clear

Create a collage with a given width and height, from a collection of 2D forms. There are no strict positioning relationships between forms, so you are free to do all kinds of 2D graphics.

The same applies to move, switching

Move a form by the given amount. This is a relative translation so (move (10,10) form) would move form ten pixels up and ten pixels to the right.

with

Move a form by the given amount (x, y). This is a relative translation so (move (5,10) form) would move form five pixels to the right and ten pixels up.

made it obvious to my student that for some reason their coordinate system was backwards compared to everyone else.

[eeue56]

The text as written should make clear which of x and y is considered the left one?

I personally didn't have any issues understanding it, but when they mentioned being confused by it, I can certainly see where they're coming from - but that's just because usually I would refer to arguments as nth argument. In this case, I would think that using nth argument would have the potential to be equally confusing, especially if you start talking about the 1st signal or the 2nd signal being dropped - it would imply an order to something unordered (signals coming in at the same time).

With an infix example, left and right certainly are a lot more obvious - I guess the difference here is that because the arguments are on different lines, it may lead to a different interpretation. The reader may left feeling like they are expected to know which is left and right in the implementation, as the chap on IRC did yesterday. But I don't know if there's a right answer here or not, really.

As to @rgrempel's point, the one that popped up in my head as a good example is the documentation for Graphics.Collage.collage, which a student complained to me about.

A collage is a collection of 2D forms. There are no strict positioning relationships between forms, so you are free to do all kinds of 2D graphics.

They were used to defining things as height, width, and thus were confused when their collage didn't come out as expected - simply naming the arguments in the documentation would've prevented their confusion. Perhaps adding width, height to the docs would've made it more clear

Create a collage with a given width and height, from a collection of 2D forms. There are no strict positioning relationships between forms, so you are free to do all kinds of 2D graphics.

The same applies to move, switching

Move a form by the given amount. This is a relative translation so (move (10,10) form) would move form ten pixels up and ten pixels to the right.

with

Move a form by the given amount (x, y). This is a relative translation so (move (5,10) form) would move form five pixels to the right and ten pixels up.

made it obvious to my student that for some reason their coordinate system was backwards compared to everyone else.

[jvoigtlaender]

Yes, I see. The case of move is particularly nasty, since the current wording with "up" being mentioned first could leave one to assume that the first pair component is about up and down.

I guess the best to be done here is to fix the individual cases where something potentially confusing like this appears in the docs.

@evancz, do I have free reign to merge this and similar doc improvements?

[jvoigtlaender]

Yes, I see. The case of move is particularly nasty, since the current wording with "up" being mentioned first could leave one to assume that the first pair component is about up and down.

I guess the best to be done here is to fix the individual cases where something potentially confusing like this appears in the docs.

@evancz, do I have free reign to merge this and similar doc improvements?

[jvoigtlaender]

Ah, for the specific case, reading the new sentence in context: Adding that sentence might create semantic confusion here. Because it makes it sound as if it could actually happen that Mouse.position and Time.fps fire at the same time. Whereas we are telling people (on the mailing list, though probably not explicitly anywhere in the docs) that signals fed by different sources (like here: mouse and timer) will never fire at the same time.

So maybe a less invasive fix is possible here that does not give this impression? Maybe something like just saying in the brackets "(...; above that [the dropped stuff] would be the update from the fps-derived signal)". Though that may still give the impression that in the given example a clash could indeed occur, which is not actually the case.

[jvoigtlaender]

Ah, for the specific case, reading the new sentence in context: Adding that sentence might create semantic confusion here. Because it makes it sound as if it could actually happen that Mouse.position and Time.fps fire at the same time. Whereas we are telling people (on the mailing list, though probably not explicitly anywhere in the docs) that signals fed by different sources (like here: mouse and timer) will never fire at the same time.

So maybe a less invasive fix is possible here that does not give this impression? Maybe something like just saying in the brackets "(...; above that [the dropped stuff] would be the update from the fps-derived signal)". Though that may still give the impression that in the given example a clash could indeed occur, which is not actually the case.

[rgrempel]

As for this particular example, I don't think "the left update wins" is actually all that clear. My first thought when I originally read it (being new to Elm) was "Hmm, I wonder what makes an update 'left' or 'right' -- perhaps there is something about Elm signals that makes them have handed-ness". Of course, that seems silly to me now -- but, especially for newbies without Haskell background, Elm is exotic enough (in a nice way) that you don't necessarily immediately dismiss the idea that things might have properties that you haven't heard of before.

Now, if it had said "the update provided by the left parameter wins", then I suppose I would have figured that out pretty fast. Although, as @eeue56 points out, the usual idiom elsewhere is to refer to the first parameter or second parameter -- perhaps referring to left and right parameters is a Haskell idiom (I don't know). If there were three parameters, would the second parameter be the 'middle' parameter?

In any event, when I saw the parameter names, I thought "Aha -- now I see clearly what's going on."

And, I know that when I'm writing documentation for my own packages, I struggle a little bit to know exactly how to refer to parameters. In jsdoc or javadoc, I'm used to referring to the parameters by name. But, in Elm documentation, it's essentially a bad idea to do that, because the documentation doesn't show the names. So, there is a mis-match -- it potentially seems perfectly clear to the documentation writer, because the documentation writer can see the names. But the reader will not. So, the documentation writer has a kind of false confidence that the documentation will make sense -- it might make sense in a given case, but that's just fortunate.

Anyway, when I have a spare hour, I'll scan through core and see if I can come up with other examples.

[rgrempel]

As for this particular example, I don't think "the left update wins" is actually all that clear. My first thought when I originally read it (being new to Elm) was "Hmm, I wonder what makes an update 'left' or 'right' -- perhaps there is something about Elm signals that makes them have handed-ness". Of course, that seems silly to me now -- but, especially for newbies without Haskell background, Elm is exotic enough (in a nice way) that you don't necessarily immediately dismiss the idea that things might have properties that you haven't heard of before.

Now, if it had said "the update provided by the left parameter wins", then I suppose I would have figured that out pretty fast. Although, as @eeue56 points out, the usual idiom elsewhere is to refer to the first parameter or second parameter -- perhaps referring to left and right parameters is a Haskell idiom (I don't know). If there were three parameters, would the second parameter be the 'middle' parameter?

In any event, when I saw the parameter names, I thought "Aha -- now I see clearly what's going on."

And, I know that when I'm writing documentation for my own packages, I struggle a little bit to know exactly how to refer to parameters. In jsdoc or javadoc, I'm used to referring to the parameters by name. But, in Elm documentation, it's essentially a bad idea to do that, because the documentation doesn't show the names. So, there is a mis-match -- it potentially seems perfectly clear to the documentation writer, because the documentation writer can see the names. But the reader will not. So, the documentation writer has a kind of false confidence that the documentation will make sense -- it might make sense in a given case, but that's just fortunate.

Anyway, when I have a spare hour, I'll scan through core and see if I can come up with other examples.

[eeue56]

For the case of move I already submitted a PR and that was merged, but I haven't noted any of the examples I've come across yet - I'll talk with the student who had issues understanding and see which ones apart from collage they got confused by, and make a new issue for them.

signals fed by different sources (like here: mouse and timer) will never fire at the same time.

If that is the case, that two Signals from different sources will never collide, then the docs here need to be changed - my understanding from the source code for genericMerge was that always was used to select the winning signal, and therefore left always wins since always : a -> b -> a. But now reading it again with your comment in mind, it is clear that can't happen due to the parent id checks.

maybe a less invasive fix is possible here that does not give this impression?

I think with the above in mind, it might be good to have somewhere else in the docs to refer to the algorithms used for Signal merge/map/foldp. The current docs on Signals on elm-lang could probably do with updating, to make it clearer how the Signals libraries work. It's been a while since I've read the Evan's papers, so I don't know which bits exactly are explained in the papers - but I don't remember merges being explained.

If an update comes from either of the incoming signals, it updates the outgoing signal. If an update comes on both signals at the same time, the left update wins (i.e., the right update is discarded).

So perhaps something along the lines of

If an update comes from either of the incoming signals, it updates the outgoing signal. If the two merged input signals are from the same source at the same time, then the left signal wins and the right signal is discarded.

How's that? I still feel it might be good to have an example of when it would be discarded and wouldn't be discarded, though that may be more suited to documentation on elm-lang rather than for core-documentation.

[eeue56]

For the case of move I already submitted a PR and that was merged, but I haven't noted any of the examples I've come across yet - I'll talk with the student who had issues understanding and see which ones apart from collage they got confused by, and make a new issue for them.

signals fed by different sources (like here: mouse and timer) will never fire at the same time.

If that is the case, that two Signals from different sources will never collide, then the docs here need to be changed - my understanding from the source code for genericMerge was that always was used to select the winning signal, and therefore left always wins since always : a -> b -> a. But now reading it again with your comment in mind, it is clear that can't happen due to the parent id checks.

maybe a less invasive fix is possible here that does not give this impression?

I think with the above in mind, it might be good to have somewhere else in the docs to refer to the algorithms used for Signal merge/map/foldp. The current docs on Signals on elm-lang could probably do with updating, to make it clearer how the Signals libraries work. It's been a while since I've read the Evan's papers, so I don't know which bits exactly are explained in the papers - but I don't remember merges being explained.

If an update comes from either of the incoming signals, it updates the outgoing signal. If an update comes on both signals at the same time, the left update wins (i.e., the right update is discarded).

So perhaps something along the lines of

If an update comes from either of the incoming signals, it updates the outgoing signal. If the two merged input signals are from the same source at the same time, then the left signal wins and the right signal is discarded.

How's that? I still feel it might be good to have an example of when it would be discarded and wouldn't be discarded, though that may be more suited to documentation on elm-lang rather than for core-documentation.

[jvoigtlaender]

The thing is: While it is (currently) true that two signals originating from different "event sources" will never fire at the same time, I have the impression Evan doesn't want to have this promise made or implied in the documentation. (Different implementation strategies could be used for the Elm runtime, and then the statement may stop being true. That's why I said in a comment above that we do tell people this on the mailing list but it's not written in the docs.)

[jvoigtlaender]

The thing is: While it is (currently) true that two signals originating from different "event sources" will never fire at the same time, I have the impression Evan doesn't want to have this promise made or implied in the documentation. (Different implementation strategies could be used for the Elm runtime, and then the statement may stop being true. That's why I said in a comment above that we do tell people this on the mailing list but it's not written in the docs.)

[eeue56]

Ah, I see. In that case I'm not sure on the best wording here. Any thoughts? My gut instinct would be to document it as it works currently, with a note that it may be subject to change later in the future.

[eeue56]

Ah, I see. In that case I'm not sure on the best wording here. Any thoughts? My gut instinct would be to document it as it works currently, with a note that it may be subject to change later in the future.

[jvoigtlaender]

I don't really understand why expressing "from the same source at the same time" is important for understanding what this function does. Why isn't "at the same time" enough? It is currently true that two events from different sources cannot occur at the same time, so adding "from the same source" is not wrong, but redundant right now. If the runtime changes at some point then it might be the case that events from different sources can occur at the same time, but when that happens, I expect that merge's behavior will be such that "from the same source at the same time" will become incorrect, and only "at the same time" will be correct.

[jvoigtlaender]

I don't really understand why expressing "from the same source at the same time" is important for understanding what this function does. Why isn't "at the same time" enough? It is currently true that two events from different sources cannot occur at the same time, so adding "from the same source" is not wrong, but redundant right now. If the runtime changes at some point then it might be the case that events from different sources can occur at the same time, but when that happens, I expect that merge's behavior will be such that "from the same source at the same time" will become incorrect, and only "at the same time" will be correct.

[rgrempel]

I must admit that I initially found the whole concept of throwing away an event because it arrived "at the same time" as another event to be a little puzzling, in the "why would you want to do that" sense. After all, the Elm architecture encourages you to merge multiple event sources -- why would I want, at some random (and rare) moment, to drop one of the events? I mean, I understand that it would be extremely rare, given the granularity of "same time", but still -- why would you want that? There's nothing about "same time" that inherently makes me want to drop an event.

However, when I saw it said that events from different sources can never occur at the same time, then I understood that there could be a use case for dropping an event. Imagine a signal graph with various maps & merges forming a bit of a diamond -- so that in some cases an event from one source might trigger an event further down the signal graph on multiple merged input nodes. (Whereas in other cases those nodes fire separately, triggered by other sources). In that case, the two events arriving at the same time actually have the same genesis -- that is, they arise from the same original event (if you think of 'original event' as the event which originally enters the signal graph).

Now, in that case, I can imagine that you might want to be able to drop one of the events. But that is because in some sense they are the 'same' event (or, to be more precise, entered the signal graph as the same event). And it seems to me the only way that 'same time' makes any sense is as a proxy for 'entered the signal graph as the same event'.

[rgrempel]

I must admit that I initially found the whole concept of throwing away an event because it arrived "at the same time" as another event to be a little puzzling, in the "why would you want to do that" sense. After all, the Elm architecture encourages you to merge multiple event sources -- why would I want, at some random (and rare) moment, to drop one of the events? I mean, I understand that it would be extremely rare, given the granularity of "same time", but still -- why would you want that? There's nothing about "same time" that inherently makes me want to drop an event.

However, when I saw it said that events from different sources can never occur at the same time, then I understood that there could be a use case for dropping an event. Imagine a signal graph with various maps & merges forming a bit of a diamond -- so that in some cases an event from one source might trigger an event further down the signal graph on multiple merged input nodes. (Whereas in other cases those nodes fire separately, triggered by other sources). In that case, the two events arriving at the same time actually have the same genesis -- that is, they arise from the same original event (if you think of 'original event' as the event which originally enters the signal graph).

Now, in that case, I can imagine that you might want to be able to drop one of the events. But that is because in some sense they are the 'same' event (or, to be more precise, entered the signal graph as the same event). And it seems to me the only way that 'same time' makes any sense is as a proxy for 'entered the signal graph as the same event'.

[jvoigtlaender]

@rgrempel, there are valuable considerations in your comment. It does seem to me this is not anymore about "just" clarifying the documentation of merge, so I'm not sure how to move forward from here.

Maybe what you say is an argument for rethinking the approach of not committing, in the documentation, to specific semantics of "same" vs. "different" event sources. Maybe also relevant would be considerations to make the genericMerge function from the JavaScript runtime (which underlies the Elm merge, but is more powerful than it) available to users of core? But these are general API considerations that seem to really transcend the documentation issue at hand.

[jvoigtlaender]

@rgrempel, there are valuable considerations in your comment. It does seem to me this is not anymore about "just" clarifying the documentation of merge, so I'm not sure how to move forward from here.

Maybe what you say is an argument for rethinking the approach of not committing, in the documentation, to specific semantics of "same" vs. "different" event sources. Maybe also relevant would be considerations to make the genericMerge function from the JavaScript runtime (which underlies the Elm merge, but is more powerful than it) available to users of core? But these are general API considerations that seem to really transcend the documentation issue at hand.

[eeue56]

Now, in that case, I can imagine that you might want to be able to drop one of the events. But that is because in some sense they are the 'same' event

This is the reason I feel that the documentation (here)[http://elm-lang.org/guide/reactivity#Signals] should be expanded a little. The only discussion on merge/foldp/map/filter there is through the graph and just listing the API. It should be the other way around, the documentation on elm-lang should cover the way Elm's Signals work, and core should briefly define the API and example usage and refer back to elm-lang for further information.

make the genericMerge function from the JavaScript runtime available to users of core

This would probably help to some extend, especially if it shows Signal.merge's implementation as an example (just genericMerge always left right), but I don't think it fully answers the issue of sources - it would still have the issue of what language to use when talking about conflict resolution.

these are general API considerations that seem to really transcend the documentation issue at hand.

Perhaps we should make a new issue for further discussion along those lines, and for now close this PR for now

[eeue56]

Now, in that case, I can imagine that you might want to be able to drop one of the events. But that is because in some sense they are the 'same' event

This is the reason I feel that the documentation (here)[http://elm-lang.org/guide/reactivity#Signals] should be expanded a little. The only discussion on merge/foldp/map/filter there is through the graph and just listing the API. It should be the other way around, the documentation on elm-lang should cover the way Elm's Signals work, and core should briefly define the API and example usage and refer back to elm-lang for further information.

make the genericMerge function from the JavaScript runtime available to users of core

This would probably help to some extend, especially if it shows Signal.merge's implementation as an example (just genericMerge always left right), but I don't think it fully answers the issue of sources - it would still have the issue of what language to use when talking about conflict resolution.

these are general API considerations that seem to really transcend the documentation issue at hand.

Perhaps we should make a new issue for further discussion along those lines, and for now close this PR for now

[jvoigtlaender]

I have made two pull requests about documentation of collage and merge (#405 and #406), picking up suggestions from the discussion above.

As suggested in the last comment by @eeue56, I'll close this issue here.

Discussion of the more general concerns from @rgrempel's comment above could be continued in a fresh issue.

[jvoigtlaender]

I have made two pull requests about documentation of collage and merge (#405 and #406), picking up suggestions from the discussion above.

As suggested in the last comment by @eeue56, I'll close this issue here.

Discussion of the more general concerns from @rgrempel's comment above could be continued in a fresh issue.