Complete package documentation

[jhmigueles]

Package documentation has been quickly and not very-carefully drafted, especially there are missing references and citations that should be included.