In languages like OCaml, or Haskell the signature provides a lot. In this particular case, if you think about it, you conclude that it's almost impossible to build any other implementation: You get a function from 'a to 'b and a list of 'a thingies. Now how on earth do I use these to get to a list of 'b thingies? No documentation needed IMNSHO ;)
What if you use a vector whole length is indexed by a Natural in the type signature? It would still allow permutations and such (like reverse), but not tail.
Using a dependent type system, it would actually be possible to statically ensure that map can only map, and do nothing else whatsoever, but it does become rather unwieldy.
List.map : ('a -> 'b) -> 'a list -> 'b list
In languages like OCaml, or Haskell the signature provides a lot. In this particular case, if you think about it, you conclude that it's almost impossible to build any other implementation: You get a function from 'a to 'b and a list of 'a thingies. Now how on earth do I use these to get to a list of 'b thingies? No documentation needed IMNSHO ;)