Improve docs for git_index_entry flag masks

The constants for extracting data from git_index_entry flags and
flags_extended are not named in a way that makes it easy to know
where to use each one.  This improves the docs for the flags (and
slightly reorganizes them), so it should be more obvious.
Add APIs to dup and free git_index_entrys

This adds git_index_entry_dup to make a copy of an existing entry
and git_index_entry_free to release the memory of the copy.  It
also updates the documentation for git_index_get_bypath and
git_index_get_byindex to make it clear that the returned structure
should *not* be modified.
Remove entry dup/free functions and fix comments

This removes the functions to duplicate and free copies of a
git_index_entry and updates the comments to explain that you
should just use the public definition of the struct as needed.
Update index.h docs

Move the git_index_entry to the very top, since it provides the
main structure that needs to be understood by the reader, then
move the bitmasks for the flags and the flags_extended under that
since they are details for looking at particular fields of the
structure.
Merge pull request #1579 from arrbee/index-entry-dup-and-free

Index entry dup and free