This should have an `@example`.  In general, all non-trivial functions should have an `@example`.  CC @ognjenb.