Html.Lazy documentation could be clearer

[wohanley]

Followup from #149:

I was using Javascript to add nodes as children of a node created by Elm. The Elm-created parent node and the JS-created nodes were both entirely dependent on a single field in the Elm model that I sent to JS via a port.

The command to add the child nodes in JS is sent if and only if the field they depend on is updated. I wanted to guarantee that Elm would redraw the parent node only under the same circumstances, so the nodes created by JS wouldn't get clobbered.

lazy's documentation suggests, to me, that it's a good tool for this job:

• "It checks to see if all the arguments are equal. If so, it skips calling the function!"
• "During diffing, we can check to see if model is referentially equal to the previous value used, and if so, we just stop. No need to build up the tree structure and diff it"

These do broadly describe how lazy works, but neither is AFAICT necessarily true. It would have been useful to me to know that using lazy won't guarantee that things work that way all the time, and that there are other mechanisms that may still result in your function being called.

The note about lazy being a performance optimization is a nod in that direction, and it would help to firmly make the point that it's only for performance optimization, and you shouldn't rely on it for correctness. Replacing "If so, it skips calling the function" with "If so, we might be able to skip calling the function" would help make that point, as would "During diffing, sometimes we can check..."

I don't think that lazy's docs explicitly claim that it does what I wanted, but they don't not claim it, and that's basically what would have helped me.

[process-bot]

Thanks for the issue! 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.