Go documentation for all public functions

1 files changed, 31 insertions, 0 deletions

diff --git a/gemini.go b/gemini.go
index 7e106b7..63477d5 100644
--- a/gemini.go
+++ b/gemini.go
@@ -19,6 +19,37 @@ const (
 	reponamekey = "syw_reponame"
 )
 
+// GeminiRouter builds a router that will handle requests into a directory of git repositories.
+//
+// The routes it defines are:
+//    /                                       gemtext listing of the repositories in the directory
+//    /:syw_reponame[/]                       gemtext overview of the repository
+//    /:syw_reponame/branches                 gemtext list of branches/heads
+//    /:syw_reponame/tags                     gemtext listing of tags
+//    /:syw_reponame/refs/:ref/               gemtext overview of a ref
+//    /:syw_reponame/refs/:ref/tree/*path     gemtext listing of directories, raw files
+//    /:syw_reponame/diffstat/:fromref/:toref text/plain diffstat between two refs
+//    /:syw_reponame/diff/:fromref/:toref     text/x-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 even be nil, but otherwise
+// the template names used are:
+//    repo_root.gmi   gemtext at /
+//    repo_home.gmi   gemtext at /:syw_reponame/
+//    branch_list.gmi gemtext at /:syw_reponame/branches
+//    tag_list.gmi    gemtext at /:syw_reponame/tags
+//    ref.gmi         gemtext at /:syw_reponame/refs/:ref/
+//    tree.gmi        gemtext for directories requested under /:syw_reponame/refs/:ref/tree/*path
+//                    (file paths return the raw files without any template involved)
+//    diffstat.gmi    the plaintext diffstat at /:syw_reponame/diffstat/:fromref/:toref
+//    diff.gmi        the text/x-diff at /:syw_reponame/diff/:fromref/:toref
+//
+// Most of the templates above are rendered with an object with 3 fields:
+//    Ctx:    the context.Context from the request
+//    Repo:   a *syw.Repository object corresponding to <repodir>/:syw_reponame
+//    Params: a map[string]string of the route parameters
+//
+// The only exception is repo_root.gmi, which is rendered with a slice of the repo names instead.
 func GeminiRouter(repodir string, overrides *template.Template) *sliderule.Router {
 	tmpl, err := addTemplates(geminiTemplate, overrides)
 	if err != nil {