docs: add some more

Author: crhntr

README.md

@@ -1,9 +1,7 @@
 # Muxt [![Go Reference](https://pkg.go.dev/badge/github.com/crhntr/muxt.svg)](https://pkg.go.dev/github.com/crhntr/muxt) [![Go](https://github.com/crhntr/muxt/actions/workflows/go.yml/badge.svg)](https://github.com/crhntr/muxt/actions/workflows/go.yml)
 
-Since Go 1.22, the standard library route **mu**ltiple**x**er [`*http.ServeMux`](https://pkg.go.dev/net/http#ServeMux) uses http methods, hosts, and path parameters.
-Muxt extends this syntax to add method signatures and type static analysis based template type safety to make it faster to write and test server side rendered hypermedia web applications.
-
-Muxt generates Go code. It does not require you to add any dependencies outside the Go standard library.
+**Muxt** is a Go code generator that helps you build server-side rendered web apps with minimal overhead, leveraging Go 1.22’s improved `http.ServeMux` and standard `html/template` features.
+No extra runtime dependencies are required—just plain Go code.
 
 - It allows you to register HTTP routes from [HTML templates](https://pkg.go.dev/html/template)
 - It generates handler functions and registers them on an [`*http.ServeMux`](https://pkg.go.dev/net/http#ServeMux)
@@ -90,145 +88,6 @@ var (
 
 ```
 
-### Making Template Source Files Discoverable
-
-Muxt needs your template source files to be embedded in the package in the current directory for it to discover and parse them (see the "Go Generate Comment Example" above).
-
-You need to add a globally scoped variable with type `embed.FS` (like `templatesSource` in the example).
-It should be passed into a call either the function `"html/template".ParseFS` or method `"html/template".Template.ParseFS`.
-Before it does so, it can call any of the following functions or methods in the right hand side of the `templates` variable declaration.
-
-Muxt will call any of the functions:
-- [`Must`](https://pkg.go.dev/html/template#Must)
-- [`Parse`](https://pkg.go.dev/html/template#Parse)
-- [`New`](https://pkg.go.dev/html/template#New)
-- [`ParseFS`](https://pkg.go.dev/html/template#ParseFS)
-
-or methods:
-- [`Template.Parse`](https://pkg.go.dev/html/template#Template.Parse)
-- [`Template.New`](https://pkg.go.dev/html/template#Template.New)
-- [`Template.ParseFS`](https://pkg.go.dev/html/template#Template.ParseFS)
-- [`Template.Delims`](https://pkg.go.dev/html/template#Template.Delims)
-- [`Template.Option`](https://pkg.go.dev/html/template#Template.Option)
-- [`Template.Funcs`](https://pkg.go.dev/html/template#Template.Option)
-
-Muxt iterates over the resulting parsed templates to discover templates matching the template name pattern documented in the "Naming Templates" section below. 
-
-### Naming Templates
-
-`muxt generate` will read your embedded HTML templates and generate/register an [`http.HandlerFunc`](https://pkg.go.dev/net/http#HandlerFunc) for each template with a name that matches an expected patten.
-
-If the template name does not match the pattern, it is ignored by muxt.
-
-Since Go 1.22, the standard library route **mu**ltiple**x**er can parse path parameters.
-
-It has expects strings like this
-
-`[METHOD ][HOST]/[PATH]`
-
-Muxt extends this a little bit.
-
-`[METHOD ][HOST]/[PATH ][HTTP_STATUS ][CALL]`
-
-A template name that muxt understands looks like this:
-
-```gotemplate
-{{define "GET /greet/{language} 200 Greeting(ctx, language)" }}
-    <h1>{{.Hello}}</h1>
-{{end}}
-```
-
-In this template name
-- Passed through to `http.ServeMux`
-  - we define the HTTP Method `GET`,
-  - the path prefix `/greet/`
-  - the path parameter called `language` (available in the call scope as `language`)
-- Used by muxt to generate a `http.HandlerFunc`
-  - the status code to use when muxt calls WriteHeader is `200` aka `http.StatusOK`
-  - the method name on the configured receiver to call is `Greeting`
-  - the parameters to pass to `Greeting` are `ctx` and `language`
-
-#### [`*http.ServeMux`](https://pkg.go.dev/net/http#ServeMux) Patterns
-
-Here is an excerpt from [the standard libary documentation.](https://pkg.go.dev/net/http#hdr-Patterns-ServeMux)
-
-> Patterns can match the method, host and path of a request. Some examples:
-> - "/index.html" matches the path "/index.html" for any host and method.
-> - "GET /static/" matches a GET request whose path begins with "/static/".
-> - "example.com/" matches any request to the host "example.com".
-> - "example.com/{$}" matches requests with host "example.com" and path "/".
-> - "/b/{bucket}/o/{objectname...}" matches paths whose first segment is "b" and whose third segment is "o". The name "bucket" denotes the second segment and "objectname" denotes the remainder of the path.
-
-#### The Method Call Scope
-
-There are three parameters you can pass to a method that always generate the same code
-
-- `ctx` -> `http.Request.Context`
-- `request` -> `*http.Request`
-- `response` -> `http.ResponseWriter` (if you use this, muxt won't generate code to call WriteHeader, you have to do this)
-
-Using these three, the generated code will look something like this.
-
-Given `{{define "GET / F(ctx, response, request)"}}Hello{{end}}`,
-
-You will get a handler generated like this:
-
-```go
-package main
-
-import (
-    "context"
-    "net/http"
-)
-
-type RoutesReceiver interface {
-  F(ctx context.Context, response http.ResponseWriter, request *http.Request) any
-}
-
-func routes(mux *http.ServeMux, receiver RoutesReceiver) {
-  mux.HandleFunc("GET /", func(response http.ResponseWriter, request *http.Request) {
-    ctx := request.Context()
-    data := receiver.F(ctx, response, request)
-    execute(response, request, false, "GET / F(ctx, response, request)", http.StatusOK, data)
-  })
-}
-
-func execute(http.ResponseWriter, *http.Request, bool, string, int, any) {}
-```
-
-You can also map path values from the path pattern to identifiers and pass them to your handler.
-
-
-Given `{{define "GET /articles/{id} ReadArticle(ctx, id)"}}{{end}}`,
-
-You will get a handler generated like this:
-
-```go
-package main
-
-import (
-  "context"
-  "net/http"
-)
-
-type RoutesReceiver interface {
-  ReadArticle(ctx context.Context, id string) any
-}
-
-func routes(mux *http.ServeMux, receiver RoutesReceiver) {
-  mux.HandleFunc("GET /articles/{id}", func(response http.ResponseWriter, request *http.Request) {
-    ctx := request.Context()
-    id := request.PathValue("id")
-    data := receiver.ReadArticle(ctx, id)
-    execute(response, request, true, "GET /articles/{id} ReadArticle(ctx, id)", http.StatusOK, data)
-  })
-}
-
-func execute(http.ResponseWriter, *http.Request, bool, string, int, any) {}
-```
-
-_TODO add more documentation on form and typed arguments_
-
 ## Examples
 
 The [example directory](example) has a worked example.

docs/action_type_checking.md

@@ -0,0 +1,14 @@
+# Action Type Checking
+
+`muxt check`
+
+Does best effort static analysis of template actions given the results from endpoint methods.
+It works in many (and some not so) simple cases.
+Template execution does a bunch of runtime evaluation that makes complete type checking impossible.
+Avoid using the empty interface and you'll probably be fine.
+
+If you wanna check out the code, it is in ./internal/templatetype.
+At some point I'd like to open source that as a subcomponent. 
+I also want to support explicitly setting a template type via `gotype: ` comments that GoLand (by JetBrains) uses for tab completion.
+
+I also would like to extend this code to create better template documentation and maybe a storybook kind thing... someday. 

docs/call_parameters.md

@@ -0,0 +1,79 @@
+# Method Parameter Field Sets
+
+This is the (wip) "argument" documentation.
+
+## The Method Call Scope
+
+There are three parameters you can pass to a method that always generate the same code
+
+- `ctx` -> `http.Request.Context`
+- `request` -> `*http.Request`
+- `response` -> `http.ResponseWriter` (if you use this, muxt won't generate code to call WriteHeader, you have to do this)
+
+Using these three, the generated code will look something like this.
+
+Given `{{define "GET / F(ctx, response, request)"}}Hello{{end}}`,
+
+You will get a handler generated like this:
+
+```go
+package main
+
+import (
+    "context"
+    "net/http"
+)
+
+type RoutesReceiver interface {
+  F(ctx context.Context, response http.ResponseWriter, request *http.Request) any
+}
+
+func routes(mux *http.ServeMux, receiver RoutesReceiver) {
+  mux.HandleFunc("GET /", func(response http.ResponseWriter, request *http.Request) {
+    ctx := request.Context()
+    data := receiver.F(ctx, response, request)
+    execute(response, request, false, "GET / F(ctx, response, request)", http.StatusOK, data)
+  })
+}
+
+func execute(http.ResponseWriter, *http.Request, bool, string, int, any) {}
+```
+
+You can also map path values from the path pattern to identifiers and pass them to your handler.
+
+
+Given `{{define "GET /articles/{id} ReadArticle(ctx, id)"}}{{end}}`,
+
+You will get a handler generated like this:
+
+```go
+package main
+
+import (
+  "context"
+  "net/http"
+)
+
+type RoutesReceiver interface {
+  ReadArticle(ctx context.Context, id string) any
+}
+
+func routes(mux *http.ServeMux, receiver RoutesReceiver) {
+  mux.HandleFunc("GET /articles/{id}", func(response http.ResponseWriter, request *http.Request) {
+    ctx := request.Context()
+    id := request.PathValue("id")
+    data := receiver.ReadArticle(ctx, id)
+    execute(response, request, true, "GET /articles/{id} ReadArticle(ctx, id)", http.StatusOK, data)
+  })
+}
+
+func execute(http.ResponseWriter, *http.Request, bool, string, int, any) {}
+```
+
+## Parsing
+
+Many basic Go types are supported.
+
+Integer variants are most common.
+
+If a type implements [`encoding.TextUmarshaler`](https://pkg.go.dev/encoding#TextUnmarshaler) we will use that.

docs/call_results.md

@@ -0,0 +1,25 @@
+# Method Result Field Sets
+
+This is the (wip) "returns" documentation.
+
+It's kinda similar to template functions.
+
+You *should* just return one struct value (including maybe one or more error fields).
+
+However, you can also return a value and an error or a boolean.
+
+The following would be acceptable result sets.
+
+```go
+package domain
+
+type T struct{
+	MissingDataReason error
+}
+
+type Server struct{}
+
+func (Server) F1() T { return T{}}
+func (Server) F2() (T, bool) { return T{}, false}
+func (Server) F3() (T, error) { return T{}, nil}
+```

docs/custom_execute_func.md

@@ -0,0 +1,6 @@
+You can write your own version of the execute function.
+
+Just copy the signature and replace the body as you like.
+
+Remember to honor the "writeHeader" parameter.
+If a method receives a response writer, you should expect that method call WriteHeader and not do so in your execute implementation.