Go documentation for all public functions

1 files changed, 41 insertions, 0 deletions

diff --git a/gopher.go b/gopher.go
index c725d68..e85599b 100644
--- a/gopher.go
+++ b/gopher.go
@@ -14,6 +14,47 @@ import (
 	"tildegit.org/tjp/sliderule/gopher"
 )
 
+// GopherRouter builds a router that will handle gopher requests in a directory of git repositories.
+//
+// The routes it defines are:
+//    /                                       gophermap listing of the repositories in the directory
+//    /:syw_reponame                          gophermap overview of the repository
+//    /:syw_reponame/branches                 gophermap list of branches/head
+//    /:syw_reponame/tags                     gophermap listing of tags
+//    /:syw_reponame/refs/:ref                gophermap overview of a ref
+//    /:syw_reponame/refs/:ref/tree           gophermap listing of a ref's root directory
+//    /:syw_reponame/refs/:ref/tree/*path     for directories: gophermap list of contents
+//                                            for files: raw files (guessed item type text/binary/image/etc)
+//    /:syw_reponame/diffstat/:fromref/:toref text diffstat between two refs
+//    /:syw_reponame/diff/:fromref/:toref     text diff between two refs
+//
+// The overrides argument can provide templates to define the behavior of nearly all of the above routes.
+// All of them have default implementations, so the argument can be nil, but otherwise the template names
+// used are:
+//    repo_root.gophermap   gophermap at /
+//    repo_home.gophermap   gophermap at /:syw_reponame
+//    branch_list.gophermap gophermap at /:syw_reponame/branches
+//    tag_list.gophermap    gophermap at /:syw_reponame/tags
+//    ref.gophermap         gophermap at /:syw_reponame/refs/:ref
+//    tree.gophermap        gophermap at direcotry paths under /:syw_reponame/refs/:ref/tree/*path
+//                          (file paths return the raw files without any template involved)
+//    diffstat.gophertext   plain text diffstat at /:syw_reponame/diffstat/:fromref/:toref
+//    diff.gophertext       plain text diff at /:syw_reponame/diff/:fromref/:toref
+//
+// Most of the templates above are rendered with an object with 6 fields:
+//    Ctx:      the context.Context from the request
+//    Repo:     a *syw.Repository corresponding to <repodir>/:syw_reponame
+//    Params:   the map[string]string of the route parameters
+//    Host:     the hostname of the running server
+//    Port:     the port number of the running server
+//    Selector: the selector in the current request
+//
+// The only exception is repo_root.gophermap, which is instead rendered with a slice of the repo names.
+//
+// All templates have 3 additional functions made available to them:
+//    combine: func(string, ...string) string - successively combines paths using url.URL.ResolveReference
+//    join: func(string, ...string) string - successively joins path segments
+//    rawtext: func(selector, host, port, text string) string renders text lines as gopher info-message lines.
 func GopherRouter(repodir string, overrides *template.Template) *sliderule.Router {
 	tmpl, err := addTemplates(gopherTemplate, overrides)
 	if err != nil {