From bc88c70725ec2025afac8714504239eb16043b85 Mon Sep 17 00:00:00 2001
From: Max Brosnahan <maximilianbrosnahan@gmail.com>
Date: Wed, 4 Nov 2015 17:34:23 -0700
Subject: [PATCH] Update documentation

---
 README.md         |  5 ++++-
 handler.go        | 24 +++++++++++++++++-------
 routed_handler.go |  8 ++++++++
 3 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 9f66c6b..d6c3337 100644
--- a/README.md
+++ b/README.md
@@ -59,7 +59,7 @@ func main() {
 	// Create a new HTTP handler for the tusd server by providing
 	// a configuration object. The DataStore property must be set
 	// in order to allow the handler to function.
-	handler, err := tusd.NewHandler(tusd.Config{
+	handler, err := tusd.NewRoutedHandler(tusd.Config{
 		BasePath:              "files/",
 		DataStore:             store,
 	})
@@ -78,6 +78,9 @@ func main() {
 }
 ```
 
+If you need to customize the GET and DELETE endpoints use `tusd.NewHandler`
+instead of `tusd.NewRoutedHandler`.
+
 ## Implementing own storages
 
 The tusd server is built to be as flexible as possible and to allow the use
diff --git a/handler.go b/handler.go
index e4ebbe2..c765278 100644
--- a/handler.go
+++ b/handler.go
@@ -48,6 +48,7 @@ var ErrStatusCodes = map[error]int{
 	ErrModifyFinal:         http.StatusForbidden,
 }
 
+// Config provides a way to configure the Handler depending on your needs.
 type Config struct {
 	// DataStore implementation used to store and retrieve the single uploads.
 	// Must no be nil.
@@ -66,6 +67,9 @@ type Config struct {
 	Logger *log.Logger
 }
 
+// Handler exposes methods to handle requests as part of the tus protocol.
+// These are PostFile and PatchFile. It also includes GetFile and DelFile
+// however these are part of the spec. They are provided for convenience.
 type Handler struct {
 	config        Config
 	dataStore     DataStore
@@ -118,6 +122,11 @@ func NewHandler(config Config) (*Handler, error) {
 	return handler, nil
 }
 
+// TusMiddleware checks various aspects of the request and ensures that it
+// conforms with the spec. Also handles method overriding for clients which
+// cannot make PATCH AND DELETE requests. If you are using the tusd handlers
+// directly you will need to wrap at least the POST and PATCH endpoints in
+// this middleware.
 func (handler *Handler) TusMiddleware(h http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		// Allow overriding the HTTP method. The reason for this is
@@ -176,8 +185,8 @@ func (handler *Handler) TusMiddleware(h http.Handler) http.Handler {
 	})
 }
 
-// Create a new file upload using the datastore after validating the length
-// and parsing the metadata.
+// PostFile creates a new file upload using the datastore after validating the
+// length and parsing the metadata.
 func (handler *Handler) PostFile(w http.ResponseWriter, r *http.Request) {
 	// Parse Upload-Concat header
 	isPartial, isFinal, partialUploads, err := parseConcat(r.Header.Get("Upload-Concat"))
@@ -239,7 +248,7 @@ func (handler *Handler) PostFile(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusCreated)
 }
 
-// Returns the length and offset for the HEAD request
+// HeadFile returns the length and offset for the HEAD request
 func (handler *Handler) HeadFile(w http.ResponseWriter, r *http.Request) {
 
 	id := r.URL.Query().Get(":id")
@@ -272,8 +281,8 @@ func (handler *Handler) HeadFile(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
-// Add a chunk to an upload. Only allowed if the upload is not locked and enough
-// space is left.
+// PatchFile adds a chunk to an upload. Only allowed if the upload is not
+// locked and enough space is left.
 func (handler *Handler) PatchFile(w http.ResponseWriter, r *http.Request) {
 
 	//Check for presence of application/offset+octet-stream
@@ -358,7 +367,8 @@ func (handler *Handler) PatchFile(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
-// Download a file using a GET request. This is not part of the specification.
+// GetFile handles requests to download a file using a GET request. This is not
+// part of the specification.
 func (handler *Handler) GetFile(w http.ResponseWriter, r *http.Request) {
 	id := r.URL.Query().Get(":id")
 
@@ -405,7 +415,7 @@ func (handler *Handler) GetFile(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-// Terminate an upload permanently.
+// DelFile terminates an upload permanently.
 func (handler *Handler) DelFile(w http.ResponseWriter, r *http.Request) {
 	id := r.URL.Query().Get(":id")
 
diff --git a/routed_handler.go b/routed_handler.go
index 5f31c32..0bc1681 100644
--- a/routed_handler.go
+++ b/routed_handler.go
@@ -6,12 +6,20 @@ import (
 	"github.com/bmizerany/pat"
 )
 
+// RoutedHandler is a ready to use handler with routing (using pat)
 type RoutedHandler struct {
 	handler         *Handler
 	routeHandler    http.Handler
 	CompleteUploads chan FileInfo
 }
 
+// NewRoutedHandler creates a routed tus protocol handler. This is the simplest
+// way to use tusd but may not be as configurable as you require. If you are
+// integrating this into an existing app you may like to use tusd.NewHandler
+// instead. Using tusd.NewHandler allows the tus handlers to be combined into
+// your existing router (aka mux) directly. It also allows the GET and DELETE
+// endpoints to be customized. These are not part of the protocol so can be
+// changed depending on your needs.
 func NewRoutedHandler(config Config) (*RoutedHandler, error) {
 	handler, err := NewHandler(config)
 	if err != nil {