SIANXSVC-1185: Korrektur der Dokumentation

Closes SIANXSVC-1185

e5e.go

@@ -86,7 +86,7 @@ type Request[T, TContext Data] struct {
 	Event   Event[T]          `json:"event"`
 }
 
-// Data provides a shortcut to [r.Event.Data].
+// Data provides a shortcut to the Data of the inner [Event].
 func (r Request[T, TContext]) Data() T { return r.Event.Data }
 
 // Result represents the function result value passed back to E5E.

errors.go

@@ -2,7 +2,7 @@ package e5e
 
 import "fmt"
 
-// InvalidEntrypointError is returned if the given entrypoint did not get registered on runtime.
+// InvalidEntrypointError is returned if the given entrypoint did not get registered before invoking [Start].
 type InvalidEntrypointError struct{ Entrypoint string }
 
 func (e InvalidEntrypointError) Error() string {

handler.go

@@ -8,7 +8,7 @@ import (
 
 // A Handler responds to a request.
 //
-// [Handle] should write reply headers and data to the given result and then return.
+// Handle should write the response data with optional metadata to the given result.
 // Returning signals that the request is finished.
 //
 // Except for reading the body, handlers should not modify the provided [Event].
@@ -24,9 +24,9 @@ type Handler[T, TContext Data] interface {
 
 // HandlerFactory provides an interface to a struct that wraps a job to be done
 // combined with a function that can execute it. Its main purpose is to
-// wrap a struct that contains generic types (like a Worker[T] that needs to be
-// invoked with a Request[T]) in such a way as to make it non-generic so that it can
-// be used in other non-generic code like [mux].
+// wrap a struct that contains generic types (like a Handler[T,TContext] that needs to be
+// invoked with a Request[T, TContext]) in such a way as to make it non-generic so that it can
+// be used in other non-generic code like the global mux.
 type HandlerFactory interface {
 	// Execute the handler with payload, which should be a deserializable JSON object.
 	// Any errors that occur due to deserialization or otherwise are returned.
@@ -59,5 +59,5 @@ func createHandlerFunc[T, TContext Data](f func(context.Context, Request[T, TCon
 }
 
 // Handlers returns all registered handlers.
-// It should not be modified directly, instead add new handlers only via [AddHandler] or [addHandlerSafely].
+// It should not be modified directly, instead add new handlers only via [AddHandlerFunc].
 func Handlers() map[string]HandlerFactory { return globalMux.handlers }

mux.go

@@ -32,10 +32,12 @@ func init() {
 
 // Start starts the global mux.
 //
-// The runtime arguments are read from os.Args and based on that,
-// the entrypoint which was added via [AddHandlerFunc] before that gets called.
+// On startup, the runtime arguments are read from [os.Args].
+// This determines the entrypoint to be used for incoming E5E calls.
+// Therefore, the developer must ensure, that a respective handler is registered using [AddHandlerFunc]
+// before this function is called.
 //
-// Every error that is happening will cause a panic.
+// All runtime errors panic.
 func Start(ctx context.Context) {
 	args, err := parseArguments(os.Args)
 	if err != nil {
@@ -50,6 +52,8 @@ func Start(ctx context.Context) {
 
 // AddHandlerFunc adds the handler for the given entrypoint to the global handler.
 // It panics if the entrypoint was already registered.
+//
+// Already registered handlers can be queried by calling [Handlers].
 func AddHandlerFunc[T, TContext Data](entrypoint string, fn func(context.Context, Request[T, TContext]) (*Result, error)) {
 	if err := addHandlerSafely(globalMux, entrypoint, createHandlerFunc[T, TContext](fn)); err != nil {
 		panic(err)
@@ -109,11 +113,6 @@ func parseArguments(args []string) (options, error) {
 //
 // If [options.KeepAlive] is true, the goroutine is blocked and can be cancelled
 // via the context. It also listens for incoming [syscall.SIGINT] signals and stops gracefully.
-//
-// # Example usage
-//
-//	mux := e5e.NewMux()
-//	log.Fatalf("mux error: %v", mux.Start(context.Background()))
 func (m *mux) Start(ctx context.Context, opts options) error {
 	if _, hasEntrypoint := m.handlers[opts.Entrypoint]; !hasEntrypoint {
 		return InvalidEntrypointError{opts.Entrypoint}