Enhance types documentation

[jooola]

I struggled trying to find what to write each field. So I searched a bit in the code and the specs.

I think I made some wrong assumptions, so I am open for some improvements.

A few mandatory TODO in the code should be addressed anyway.

[jooola]

And I feel some fields could use a new name as it might not always be really clear.

[coveralls]

Coverage remained the same at 99.571% when pulling 4c4a0d2e56e29bca03797ee349240ce3149b584b on jooola:enhance_types_documentation into fd77835d23990670975092c15009c75432e258ac on jpmonette:master.