After re-reading, I realize that my previous message is rather obscure and lacks clarity.
The verb “return” denotes an action, so the subject must be interpreted as being able to perform this action. Hence a possible reading as “a call to f x
returns something”. That said, such a reading is more common in imperative languages, where it’s common to look at a program as a series of instructions for the computer. In a functional language, a pure expression (without side effects) is more commonly seen as representing a value that doesn’t necessarily perform any action (like a float). In this case, my personal taste is to document on what the expression represents, and then use the verb “to be” if appropriate to describe the result of the function call.
In any case, when the OCaml expression is used for its side effects, it seems appropriate to use an action verb to document it. To continue the analogy with grammatical analysis, such an expression will often be represented by a transitive verb: a verb that needs an object complement to express its action. In OCaml type language, this could be translated as:
type 'a verb = 'a -> unit
Such an action can be executed several times with this combinator:
let times n f x = for i = 1 to n do (f x : unit) done
If we look to the type of times
we get:
val times : int -> ('a -> unit) -> 'a -> unit
and if we use our previous type aliases:
val times : int -> 'a verb -> 'a verb
In grammar, a term that takes a verb and modifies its meaning is called an adverb. In OCaml, this would be:
type 'a adverb = 'a verb -> 'a verb
In the end, for times
we would have:
val times : int -> 'a adverb
which corresponds to the grammatical function of the word “times” in English.
let write = print_endline
The following expression can be documented in this way:
(* `times n write text` writes n times `text` to stdout *)
What’s fun (pun intended) is that the documentation is a paraphrase of the OCaml code with a slight morphological variation. And indeed, that’s what the instruction does:
times 5 write "OCaml is awesome";;
OCaml is awesome
OCaml is awesome
OCaml is awesome
OCaml is awesome
OCaml is awesome
- : unit = ()
(* increment five times a reference *)
let x = ref 0 in times 5 incr x; !x;;
- : int = 5