Improve the documentation of partial functions in base

[sjakobi]

• Emphasize in which cases the function will result in an error.

• Point at total alternatives, e.g. head's documentation should mention listToMaybe.

[neongreen]

I could do it (I recently made a patch to base and it wasn't hard) but first we should find a list of partial functions in base. Is there one somewhere?

[Gurkenglas]

fromJust and head are eventually implemented using errorWithoutStackTrace, so you could search its call history in base source.

[neongreen]

Makes sense, thanks.

[sjakobi]

I could do it (I recently made a patch to base and it wasn't hard)

Sounds great! I think it's quite a bit of work, but definitely worth it!

There is also the issue of type class instances with partial methods. For example succ :: Integer -> Integer is for most purposes quite total while succ :: Bool -> Bool isn't.

Instances can have their own haddocks like the Read instance here but individual instance methods can apparently not.

[neongreen]

I'm sleepy so I'll just dump the list here:

errorWithoutStackTrace:
  • printf
  • read
  • gather
  • showInt, showIntAtBase
  • intToDigit, digitToInt
  • mallocForeignPtr, mallocForeignPtrBytes, mallocForeignPtrAlignedBytes, 
    mallocPlainForeignPtr, mallocPlainForeignPtrBytes, 
    mallocPlainForeignPtrAlignedBytes, addForeignPtrFinalizer
  • (!!)
  • (^)
  • chr
  • NonEmpty: fromList, (!!)
  • stimes, stimesMonoid, stimesIdempotentMonoid, stimesIdempotent
  • bitSize @Integer, @Natural
  • complement @Natural, pred @Natural
  • fromJust
  • the
  • registerDelay
  • maximumBy, minimumBy, genericIndex, foldr1, foldl1, minimum, maximum
  • succ, pred, toEnum, fromEnum
  • repConstr, dataTypeConstrs, indexConstr, constrIndex, 
    maxConstrIndex, mkIntegralConstr, mkRealConstr, mkCharConstr
  • gunfold for various types (?)
  • readControlMessage, sendMessage
  • newDefaultBackend
  • dynApp
  • threadWaitRead, threadWaitWrite, threadWaitReadSTM, 
    threadWaitWriteSTM on Windows
  • mfix @Maybe, @Either

errorEmptyList:
  • head, tail, init, last, foldl1, foldl1', foldr1, maximum, minimum, cycle

error:
  • lots of functions in Data.Bifoldable

Probably missed something. Also some of those already have warnings, though it might be nice to make them more unified.

[Gurkenglas]

https://hackage.haskell.org/package/base-4.9.0.0/docs/src/Data.Foldable.html#minimum

I see no errorEmptyList.

[neongreen]

The Foldable [] instance uses maximum from GHC.List, which uses errorEmptyList.

[sjakobi]

FWIW the changes can now also be submitted via https://github.com/ghc/ghc/pulls.

[nikivazou]

How about adding Liquid Haskell type signatures to constrain the domain of the partial functions and make them total?

I believe that Liquid type specifications

• are compact forma of documentation and also
• are machine checked.

We have already specified many Base functions in here

https://github.com/ucsd-progsys/liquidhaskell/tree/develop/include