Small typo in Data.Maybe docs

1

The description of isNothing at Data.Maybe source code has a typo: iff instead of if. I mention this here because I don’t know if I should open an issue at GHC gitlab just for a typo.

2 Likes
2

This is not really typo. The word ‘iff’ is used in mathematical texts to mean ‘if and only if’. In this case that means that it will return True if the input is Nothing and for any other input it will not return True.

That said, it would still be good to avoid such jargon in the documentation.

12 Likes
3

oh I didn’t notice because English is not my main language. I agree.

2 Likes
4

It remains a good question because iff isn’t that common outside of math. You could still raise an issue at the appropriate place because we want the documentation to be approachable. No doubt iff is used elsewhere in base

6 Likes
5

I think it is relatively common in technical documentation as well, e.g. the C# docs use it quite bit.
That said, I wouldn’t be against spelling out “if and only if”, especially in already relatively short docs like this.

7 Likes
6

In any case, it’s inconsistent with fromJust, which says

The fromJust function extracts the element out of a Just and throws an error if its argument is Nothing.

My preference is to use “when” for defining properties.

2 Likes
7

What would you suggest then? Something like this perhaps:

The isJust function returns True if its argument is a Just of something and False if its argument is Nothing.

8

Oh, actually it’s not inconsistent in the way that I thought. I though the use of “if” was inconsistent, but it’s used in a way where “iff” doesn’t really work, so I’m so I’m not sure I have an obvious suggestion for improvement.

Currently we have

The isNothing function returns True iff its argument is Nothing.

I could suggest

The isNothing function returns True when its argument is Nothing.

(i.e. switch “if” to “when”) but perhaps some people think that would be imprecise.

2 Likes
9

‘Returns’ always sounds a bit ‘imperative’ to me.

How about:

isNothing x yields True when x is Nothing and False otherwise.

1 Like
10

IMO, “and False otherwise” is just noise. Given an a -> Boolean, and a single short sentence describing when it returns/yields True, I’m not convinced that anyone’s really stuck wondering “and when does it return False?!”. And I appreciate the terseness of a lot of Haskell documentation.

I also like @tomjaguarpaw’s “when”, which for some reason does feel like it implies the “only if”.

1 Like
11

Well, the word yield is also overloaded in the same way and I think its meaning from Python would be even more confusing than return.

I honestly think “return” is fine, I think it’s far too common in programming jargon to talk about pure functions returning things. But if one really wants to be precise, another alternative could be

isNothing a is True when a is Nothing

But perhaps we should use wwhen for “when and only when” :face_with_tongue:

12

I wonder if debating the exact wording to use when translating

isNothing Nothing = True
isNothing _ = False

into English is even worth it. Maybe (30% serious) Haddock should just inline the implementation.

1 Like
13

Reading

-- | The 'isNothing' function returns 'True' iff its argument is 'Nothing'.

as a mathematician, the “iff” does not help at all, because there is no indication (yes, I can see the examples) what the function returns for Nothing.

This:

isNothing         :: Maybe a -> Bool
isNothing Nothing = True
isNothing _       = error "HAHA!"

So: whoever wrote that documentation and wanted to be exact, failed (miserable, I would even add). Yes, there should be a HasCallstack for error, just use whatever you want hidden inside unsafePerformIO.

15

The fact that this discussion has been opened highlights that there is a — small but existing — problem with documentation.

So I would not call it broken, but something that can be improved for better accessibility.

17

Seriously: what actually is really inconsistent is e.g. the warning about partial functions in Prelude, compare for example head:

with last:

It would be good to either make all warnings red or none, but as it is the black one is easily overlooked.

1 Like
18

Personally I don’t think it’s fine that users have to mentally amend docs of very simple functions.

3 Likes
20

Yes, I think it would indeed be good to include a quick informal explanation of modular arithmetic there.

The only drawback I see is that it takes some effort, so we may want to prioritize other more impactful changes.

4 Likes
22

The thought that one may have to consult a dictionary to understand the meaning of one of the words in the documentation for one of the simplest functions possible in Haskell isn’t making me change my mind!

Do we need then a curated list of english words that can be accepted in Haskell documentation ?

In principle I think that would be a good idea. See for example Basic English - Wikipedia

But I don’t think it’s our low-hanging fruit.

1 Like
24

Could you flesh out your reasoning a bit here? It sounds like you’re saying that because more complicated words and concepts will be encountered, it’s OK (even desirable?) to use unfamiliar words to explain simple concepts?

2 Likes
25

This is actually an example which I would actually prefer to be changed. The operator’s name is “modulo”, “modulus” is what in the documentation is called “divisor”. And the result is the remainder. I’m not a number theorist by any means, but I haven’t heard the term “Integer modulus” before.

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base .

Using x and y is also somewhat disturbing, not only for “implicit int” Fortran users ;). At least a m should be used.

Wiki links :smiley: Modular arithmetic - Wikipedia and Modulo - Wikipedia