added instructions

goreadme.go

@@ -2,16 +2,16 @@
 //
 // This package can be used as a web service, as a command line tool or as a library.
 //
-// Try the web service: [https://gotreadme.herokuapp.com](https://gotreadme.herokuapp.com)
+// Try the web service: https://gotreadme.herokuapp.com.
 //
-// Integrate directly with Github: [https://github.com/apps/goreadme](https://github.com/apps/goreadme).
+// Integrate directly with Github: https://github.com/apps/goreadme.
 //
 // Use as a command line tool:
 //
-//		$ go get github.com/posener/goreadme/...
-//		$ goreadme -h
+// 	$ go get github.com/posener/goreadme/...
+// 	$ goreadme -h
 //
-// ## Why should you use it?
+// Why should you use it?
 //
 // Both go doc and readme files are important. Go doc to be used by your user's
 // library, and README file to welcome users to use your library. They share
@@ -20,7 +20,21 @@
 // is important, and hard enough - keeping both updated is twice as hard.
 //
 // This library provides an easy way to create the one from the other. Using the
-// [goreadme Github App](https://github.com/apps/goreadme) makes it even easier.
+// goreadme Github App: https://github.com/apps/goreadme makes it even easier.
+//
+// Go Doc Instructions
+//
+// The formatting of the README.md is done by the go doc parser. This makes the
+// Result README.md a bit more limited.
+// Currently, `goreadme` supports the formatting as explained in: https://blog.golang.org/godoc-documenting-go-code.
+// Meaning:
+//
+// * A header is a single line that is separated from a paragraph above.
+//
+// * Code block is recognized by indentation.
+//
+// * URLs will just automatically converted to links
+// (Added support to local links - prefixed by dot and slash, for example: ./cmd).
 package goreadme
 
 import (
@@ -34,10 +48,9 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/posener/goreadme/internal/template"
-
 	"github.com/golang/gddo/doc"
 	"github.com/pkg/errors"
+	"github.com/posener/goreadme/internal/template"
 )
 
 // New returns a GoReadme object with a custom client.