Add package docs and project vision/goals (#5169)

* Add goals/design vision to contributing doc
* Add barebones package documentation

internal/api/doc.go

@@ -0,0 +1,2 @@
+// Package api provides the HTTP and Graphql API for the application.
+package api

internal/api/loaders/dataloaders.go

@@ -1,3 +1,7 @@
+// Package loaders contains the dataloaders used by the resolver in [api].
+// They are generated with `make generate-dataloaders`.
+// The dataloaders are used to batch requests to the database.
+
 //go:generate go run github.com/vektah/dataloaden SceneLoader int *github.com/stashapp/stash/pkg/models.Scene
 //go:generate go run github.com/vektah/dataloaden GalleryLoader int *github.com/stashapp/stash/pkg/models.Gallery
 //go:generate go run github.com/vektah/dataloaden ImageLoader int *github.com/stashapp/stash/pkg/models.Image

internal/api/server.go

@@ -75,7 +75,8 @@ func (dir osFS) Open(name string) (fs.File, error) {
 	return os.DirFS(string(dir)).Open(name)
 }
 
-// Called at startup
+// Initialize creates a new [Server] instance.
+// It assumes that the [manager.Manager] instance has been initialised.
 func Initialize() (*Server, error) {
 	mgr := manager.GetInstance()
 	cfg := mgr.Config
@@ -289,6 +290,9 @@ func Initialize() (*Server, error) {
 	return server, nil
 }
 
+// Start starts the server. It listens on the configured address and port.
+// It calls ListenAndServeTLS if TLS is configured, otherwise it calls ListenAndServe.
+// Calls to Start are blocked until the server is shutdown.
 func (s *Server) Start() error {
 	logger.Infof("stash is listening on " + s.Addr)
 	logger.Infof("stash is running at " + s.displayAddress)
@@ -300,6 +304,7 @@ func (s *Server) Start() error {
 	}
 }
 
+// Shutdown gracefully shuts down the server without interrupting any active connections.
 func (s *Server) Shutdown() {
 	err := s.Server.Shutdown(context.TODO())
 	if err != nil {

internal/api/urlbuilders/doc.go

@@ -0,0 +1,2 @@
+// Package urlbuilders provides the builders used to build URLs to pass to clients.
+package urlbuilders