[erlang-questions] On OTP rand module difference between OTP 19 and OTP 20

[Fred Hebert]

On 08/31, Loïc Hoguin wrote:
>Maybe in the Linux kernel. Outside, where there is such a thing as 
>documentation (comments are not documentation), if the code behaves 
>differently than the documentation, you open a ticket... And in that 
>case, yes, for a limited time, you will program against the behavior 
>and not against the documentation. But it's the exception, not the 
>rule.
>

I think 'it depends' truly *is* the best way to go about it. Let's see a 
few examples:

- A function does what is in the doc, but also does a bit more at the 
  same time. Do you fix by removing the additional functionality people 
  may now rely on, or by updating the doc to match the implementation?
- The documentation specifies that by sending the atom 'tsl1.3' you can 
  set up a TLS 1.3 connection, but the implementation only accepts 
  'tsl1.3' and crashes on 'tsl1.3'. Do you not update the documentation 
  for what was a typo, or do you add support for 'tsl1.3' as a 
  parameter? If anybody relied on that behaviour, they relied on the 
  code not working!
- A function for socket handling returns values such as `{error, emfile 
  | enfile | econnrefused}`. Someone finds out that the syscalls it 
  relays data to also may return `{error, eperm | eaccess}` on top of 
  what was specified before. Do you swallow the errors and mask them, or 
  update the docs? Or is it not just a bug in the docs?
- A function's doc says it sorts in a stable manner but it does not.  
  Which one should you change? There seems to be no winner on this one.
- A function logs information while it operates on data, but the 
  documentation makes no reference to it. Someone working with it in a 
  specific environment has issues with that behaviour.*

There's plenty of cases where the doc and the implementation may be 
wrong individually. Either as a mistake on either sides, by omission, or 
through a bug. Usually you have to take a pragmatic approach wondering 
which of the fixes will give the lowest conflict or impact to people 
using the code.

Now is the case of the random behaviour similar to specifying a bad type 
boundary similar to "not supporting all the errors", to a breach of a 
well-established contract, etc.? That's a really hard question, but 
saying either "the doc always wins" or "the code always wins" 
unequivocally sounds like a real bad policy to me.

Regards,
Fred.

* In adding shell history to Erlang, we got tripped up on disk_log doing 
  just that. We added a new option to force it to be silent when needed, 
  for example, so both the code and the doc required a fix!