How to document FExpr- functions?

[st-pasha]

The majority of functions in datatable operate on an FExpr (or FExpr-convertible object) and return another FExpr in turn. Thus, a signature of a typical function looks like this:

sin(x)

Parameters
----------
x: FExpr

return: FExpr

While this is technically correct, it fails to paint an accurate picture.

For example, sin(), like many other functions auto-maps over its argument. Thus if x contains several columns, then sin(x) is equivalent to [sin(x[0]), sin(x[1]), ...].

Like any unary function, sin() preserves the name of its argument: of the column x has name "ABC" then the resulting expression will also produce a column with the same name "ABC".

The function sin() works on columns of all numeric types. However, the resulting column is of type float64 (unless the input is float32 in which case the result is also float32). For other function the mapping of input stype into the output stype is more complicated. For binary functions the stype of the result depends on stypes of both arguments.

---

Thus, in order to document this function (and other functions) well, we'll need to figure out a good template how such documentation should look like; and whether we need any custom directives for this.