Update documentation to be more structured and comprehensive, so it's easier to find and use the code

[aSemy]

• group docs into chapters
• add KDoc wherever possible
• update readme to include tuples
• document generic types limitations
• document 'brand type'