wmflib: add documentation, standardize code conventions

* Instead of the :doc argument to newfunction, add a standard header to each
  file that documents that signature of the function and its purpose and
  provides at least one example.
* Also describe each function in README.md.
* Lint the code for style and uniformity, taking the output of `rubocop` as a
  guide.

Change-Id: I6838ba191c1e3b9cb47ffd01f1b1f76e2b5e1a07