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

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

docs/CONTRIBUTING.md

@@ -1,3 +1,24 @@
+## Goals and design vision
+
+The goal of stash is to be:
+- an application for organising and viewing adult content - currently this is videos and images, in future this will be extended to include audio and text content
+  - organising includes scraping of metadata from websites and metadata repositories
+- free and open-source
+- portable and offline - can be run on a USB stick without needing to install dependencies (with the exception of ffmpeg)
+- minimal, but highly extensible. The core feature set should be the minimum required to achieve the primary goal, while being extensible enough to extend via plugins
+- easy to learn and use, with minimal technical knowledge required
+
+The core stash system is not intended for:
+- managing downloading of content
+- managing content on external websites
+- publically sharing content
+
+Other requirements:
+- support as many video and image formats as possible
+- interfaces with external systems (for example stash-box) should be made as generic as possible. 
+
+Design considerations:
+- features are easy to add and difficult to remove. Large superfluous features should be scrutinised and avoided where possible (eg DLNA, filename parser). Such features should be considered for third-party plugins instead.
 
 ## Technical Debt
 Please be sure to consider how heavily your contribution impacts the maintainability of the project long term, sometimes less is more.  We don't want to merge collossal pull requests with hundreds of dependencies by a driveby contributor.

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

internal/autotag/doc.go

@@ -0,0 +1,9 @@
+// Package autotag provides the autotagging functionality for the application.
+//
+// The autotag functionality sets media metadata based on the media's path.
+// The functions in this package are in the form of {ObjectType}{TagTypes},
+// where the ObjectType is the single object instance to run on, and TagTypes
+// are the related types.
+// For example, PerformerScenes finds and tags scenes with a provided performer,
+// whereas ScenePerformers tags a single scene with any Performers that match.
+package autotag

internal/build/version.go

@@ -1,3 +1,4 @@
+// Package build provides the version information for the application.
 package build
 
 import (

internal/desktop/desktop.go

@@ -1,3 +1,4 @@
+// Package desktop provides desktop integration functionality for the application.
 package desktop
 
 import (

internal/dlna/doc.go

@@ -0,0 +1,3 @@
+// Package dlna provides the DLNA functionality for the application.
+// Much of this code is adapted from https://github.com/anacrolix/dms
+package dlna

internal/identify/identify.go

@@ -1,3 +1,6 @@
+// Package identify provides the scene identification functionality for the application.
+// The identify functionality uses scene scrapers to identify a given scene and
+// set its metadata based on the scraped data.
 package identify
 
 import (

internal/log/logger.go

@@ -1,3 +1,4 @@
+// Package log provides an implementation of [logger.LoggerImpl], using logrus.
 package log
 
 import (

internal/manager/manager.go

@@ -1,3 +1,5 @@
+// Package manager provides the core manager of the application.
+// This consolidates all the services and managers into a single struct.
 package manager
 
 import (

internal/static/embed.go

@@ -1,3 +1,4 @@
+// Package static provides the static files embedded in the application.
 package static
 
 import (

pkg/file/file.go

@@ -1,3 +1,4 @@
+// Package file provides functionality for managing, scanning and cleaning files and folders.
 package file
 
 import (

pkg/fsutil/fs.go

@@ -1,3 +1,4 @@
+// Package fsutil provides filesystem utility functions for the application.
 package fsutil
 
 import (

pkg/gallery/service.go

@@ -1,3 +1,5 @@
+// Package gallery provides application logic for managing galleries.
+// This functionality is exposed via the [Service] type.
 package gallery
 
 import (

pkg/group/doc.go

@@ -0,0 +1,2 @@
+// Package group provides the application logic for groups.
+package group

pkg/image/service.go

@@ -1,3 +1,5 @@
+// Package image provides the application logic for images.
+// The functionality is exposed via the [Service] type.
 package image
 
 import (

pkg/javascript/vm.go

@@ -1,8 +1,8 @@
+// Package javascript provides the javascript runtime for the application.
 package javascript
 
 import (
 	"fmt"
-	"net/http"
 	"os"
 	"reflect"
 
@@ -10,12 +10,9 @@ import (
 	"github.com/stashapp/stash/pkg/logger"
 )
 
+// VM is a wrapper around goja.Runtime.
 type VM struct {
 	*goja.Runtime
-
-	Progress      chan float64
-	SessionCookie *http.Cookie
-	GQLHandler    http.Handler
 }
 
 // optionalFieldNameMapper wraps a goja.FieldNameMapper and returns the field name if the wrapped mapper returns an empty string.

pkg/job/job.go

@@ -1,3 +1,4 @@
+// Package job provides the job execution and management functionality for the application.
 package job
 
 import (

pkg/match/path.go

@@ -1,3 +1,4 @@
+// Package match provides functions for matching paths to models.
 package match
 
 import (

pkg/models/doc.go

@@ -0,0 +1,2 @@
+// Package models provides application models that are used throughout the application.
+package models

pkg/models/json/json_time.go

@@ -1,3 +1,4 @@
+// Package json provides generic JSON types.
 package json
 
 import (

pkg/models/jsonschema/doc.go

@@ -0,0 +1,2 @@
+// Package jsonschema provides the JSON schema models used for importing and exporting data.
+package jsonschema

pkg/models/mocks/database.go

@@ -1,3 +1,4 @@
+// Package mocks provides mocks for various interfaces in [models].
 package mocks
 
 import (

pkg/models/paths/paths.go

@@ -1,3 +1,4 @@
+// Package paths provides functions to return paths to various resources.
 package paths
 
 import (

pkg/performer/doc.go

@@ -0,0 +1,2 @@
+// Package performer provides the application logic for performer functionality.
+package performer

pkg/pkg/pkg.go

@@ -1,3 +1,4 @@
+// Package pkg provides interfaces to interact with the package system used for plugins and scrapers.
 package pkg
 
 import (

pkg/python/exec.go

@@ -1,3 +1,4 @@
+// Package python provides utilities for working with the python executable.
 package python
 
 import (

pkg/scene/generate/generator.go

@@ -1,3 +1,4 @@
+// Package generate provides functions to generate media assets from scenes.
 package generate
 
 import (

pkg/scene/service.go

@@ -1,3 +1,5 @@
+// Package scene provides the application logic for scene functionality.
+// Most functionality is provided by [Service].
 package scene
 
 import (

pkg/scraper/scraper.go

@@ -1,3 +1,5 @@
+// Package scraper provides interfaces to interact with the scraper subsystem.
+// The [Cache] type is the main entry point to the scraper subsystem.
 package scraper
 
 import (

pkg/scraper/stashbox/stash_box.go

@@ -1,3 +1,4 @@
+// Package stashbox provides a client interface to a stash-box server instance.
 package stashbox
 
 import (

pkg/session/session.go

@@ -1,3 +1,4 @@
+// Package session provides session authentication and management for the application.
 package session
 
 import (

pkg/sliceutil/collections.go

@@ -1,3 +1,4 @@
+// Package sliceutil provides utilities for working with slices.
 package sliceutil
 
 // Index returns the first index of the provided value in the provided

pkg/sqlite/doc.go

@@ -0,0 +1,2 @@
+// Package sqlite provides interfaces to interact with the sqlite database.
+package sqlite

pkg/studio/doc.go

@@ -0,0 +1,2 @@
+// Package studio provides the application logic for studio functionality.
+package studio

pkg/tag/doc.go

@@ -0,0 +1,2 @@
+// Package tag provides application logic for tag objects.
+package tag

pkg/txn/transaction.go

@@ -1,3 +1,4 @@
+// Package txn provides functions for running transactions.
 package txn
 
 import (

pkg/utils/doc.go

@@ -0,0 +1,2 @@
+// Package utils provides various utility functions for the application.
+package utils