Unclear documentation for Decode.decode

[danfishgold]

The current function documentation is:

decode : Decoder a -> Bytes -> Maybe a

The Decoder specifies exactly how this should happen. This process may fail if the sequence of bytes is corrupted or unexpected somehow. The examples above show a case where there are not enough bytes.

What does "corrupted sequence of bytes" mean here? signedInt8 should work on any Bytes given to it. Is there a case where using it in decode yields Nothing?

If there is, I think a more explicit warning would help (and ideally some links about possible issues). If there isn't, the documentation should say that the only reason for decoding to fail is by passing the decoder a sequence of bytes that it is unable to parse.

[maca]

@danfishgold not sure if I understand, if one has a decoder that expects 3 bytes and only 2 are given, decode will return Nothing. I guess corrupted simply means the input does not conform to ones expectations possibly due to transport issues.

As a user of the library I don't find in this specific case a source of confusion

I was thinking that it would be useful that decode would return a Result then the implementer of a library could explain what went wrong in the decoding, but I think is doable by having decoders that decode to a result.

[danfishgold]

@maca

I guess corrupted simply means the input does not conform to ones expectations possibly due to transport issues.

That's what I want to find out: if I know what goes into the decode function and I know the decoder can handle it, is there still a case where decode would return Nothing?

[maca]

@danfishgold There are many instances where the decoder wont be able to handle the input. My specific scenario is a PNG decode library I am working on, if the user uploads a file that is not a PNG, the decoder will return Nothing.

[danfishgold]

I'm talking about decoders that always succeed (like signedInt8): would they ever return Nothing? The answer to that question is unclear in the docs