Improve package documentation

[jakubnowicki]

Fill in missing parts of the functions/classes/methods documentation

• add descriptions
• add returned values
• add examples

Build the documentation with roxygen2.