document (non-)usage of Free

[josharian]

I think it would be helpful to add some package-level docs around memory management. In particular, they should point out that git2go handles it by default (#209).

I'll send a PR if that'd be helpful.

I also think it'd be worth documenting the functions whose return value must not be Free'd, since there is no obvious indicator. As an example, consider Reference.Branch:

package main

import (
	"fmt"
	"log"
	"os"

	git "gopkg.in/libgit2/git2go.v26"
)

func main() {
	pwd, err := os.Getwd()
	check(err)

	repo, err := git.OpenRepositoryExtended(pwd, 0, "")
	check(err)
	defer repo.Free()

	head, err := repo.Head()
	check(err)
	defer head.Free() // can be freed

	b := head.Branch()
	defer b.Free() // cannot be freed! this program will panic.

	upstream, err := b.Upstream()
	check(err)
	defer upstream.Free() // can be freed

	fmt.Println("repo head branch is", b, "and upstream is", upstream)
}

func check(err error) {
	if err != nil {
		log.Fatal(err)
	}
}

Or do you think that Reference.Branch should be changed so that the result can be Free'd?