# HG changeset patch
# User Sascha L. Teichmann <sascha.teichmann@intevation.de>
# Date 1543946090 -3600
# Node ID b41ad15cc55f9cd17b087dacc9dbb73afb63d069
# Parent  3bf1f0de076336a12cc77763f6efe9b4091814d7
Backend: Documented the internal API of the global import queue.

diff -r 3bf1f0de0763 -r b41ad15cc55f pkg/imports/queue.go
--- a/pkg/imports/queue.go	Tue Dec 04 18:27:35 2018 +0100
+++ b/pkg/imports/queue.go	Tue Dec 04 18:54:50 2018 +0100
@@ -31,22 +31,54 @@
 )
 
 type (
+	// Feedback is passed to the Do method of a Job to log
+	// informations, warnings or errors.
 	Feedback interface {
+		// Info logs informations.
 		Info(fmt string, args ...interface{})
+		// Warn logs warnings.
 		Warn(fmt string, args ...interface{})
+		// Error logs errors.
 		Error(fmt string, args ...interface{})
 	}
 
+	// Job is the central abstraction of an import job
+	// run by the import queue.
 	Job interface {
-		Do(context.Context, int64, *sql.Conn, Feedback) (interface{}, error)
+		// Do is called to do the actual import.
+		// Bind transactions to ctx and conn, please-
+		// id is the number of the import job.
+		// feedback can be used to log the import process.
+		// If no error is return the import is assumed to
+		// be successfull. The non-error return value is
+		// serialized as a JSON string into the database as
+		// a summary to the import to be used by the review process.
+		Do(ctx context.Context, id int64, conn *sql.Conn, feedback Feedback) (interface{}, error)
+		// CleanUp is called to clean up ressources hold by the import.
+		// It is called whether the import succeeded or not.
 		CleanUp() error
 	}
 
+	// JobKind is the type of an import.
+	// Choose a unique name for every import.
 	JobKind string
 
+	// JobCreator is used to bring a job to life as it is stored
+	// in pure meta-data form to the database.
 	JobCreator interface {
+		// Create build the actual job.
+		// kind is the name of the import type.
+		// data is a free form string to pass arguments to the creation
+		// process. This is useful to tell e.g. where to find data
+		// in the file system to be used for importing.
 		Create(kind JobKind, data string) (Job, error)
+		// Depends returns a list of ressources locked by this type of import.
+		// Imports are run concurrently if they have disjoint sets
+		// of dependencies.
 		Depends() []string
+		// StageDone is called if an import is positively reviewed
+		// (state = accepted). This can be used to finalize the imported
+		// data to move it e.g from the staging area.
 		StageDone(context.Context, *sql.Tx, int64) error
 	}
 
@@ -74,6 +106,7 @@
 }
 
 var (
+	// ImportStateNames is a list of the states a job can be in.
 	ImportStateNames = []string{
 		"queued",
 		"running",
@@ -149,14 +182,20 @@
 	q.creators[kind] = jc
 }
 
+// FindJobCreator looks up a JobCreator in the global import queue.
 func FindJobCreator(kind JobKind) JobCreator {
 	return iqueue.jobCreator(kind)
 }
 
+// ImportKindNames is a list of the names of the imports the
+// global import queue supports.
 func ImportKindNames() []string {
 	return iqueue.importKindNames()
 }
 
+// RegisterJobCreator adds a JobCreator to the global import queue.
+// This a good candidate to be called in a init function for
+// a particular JobCreator.
 func RegisterJobCreator(kind JobKind, jc JobCreator) {
 	log.Printf("info: register import job creator for kind '%s'\n", kind)
 	iqueue.registerJobCreator(kind, jc)
@@ -196,6 +235,9 @@
 	return id, err
 }
 
+// AddJob adds a job to the global import queue to be executed
+// as soon as possible. This is gone in a separate Go routine
+// so this will not block.
 func AddJob(kind JobKind, user, data string) (int64, error) {
 	return iqueue.addJob(kind, user, data)
 }