From ad3d6b7fffd9ee1380e7149cc2c5bfc7c3396891 Mon Sep 17 00:00:00 2001
From: Sandro Santilli <strk@kbt.io>
Date: Tue, 15 Nov 2016 08:06:31 +0100
Subject: [PATCH] Lint and document manager api

---
 modules/process/manager.go | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/modules/process/manager.go b/modules/process/manager.go
index 4510a823cfb..2748c14bb4e 100644
--- a/modules/process/manager.go
+++ b/modules/process/manager.go
@@ -15,13 +15,14 @@ import (
 )
 
 var (
+	// ErrExecTimeout represent a timeout error
 	ErrExecTimeout = errors.New("Process execution timeout")
-)
 
-// Common timeout.
-var (
+	// DefaultTimeout is the timeout used by Exec* family
+	// of function when timeout parameter is omitted or
+	// passed as -1
 	// NOTE: could be custom in config file for default.
-	DEFAULT = 60 * time.Second
+	DefaultTimeout = 60 * time.Second
 )
 
 // Process represents a working process inherit from Gogs.
@@ -51,10 +52,13 @@ func Add(desc string, cmd *exec.Cmd) int64 {
 	return pid
 }
 
-// Exec starts executing a command in given path, it records its process and timeout.
+// ExecDir runs a command in given path and waits for its completion
+// up to the given timeout (or DefaultTimeout if -1 is given).
+// Returns its complete stdout and stderr
+// outputs and an error, if any (including timeout)
 func ExecDir(timeout time.Duration, dir, desc, cmdName string, args ...string) (string, string, error) {
 	if timeout == -1 {
-		timeout = DEFAULT
+		timeout = DefaultTimeout
 	}
 
 	bufOut := new(bytes.Buffer)
@@ -89,12 +93,17 @@ func ExecDir(timeout time.Duration, dir, desc, cmdName string, args ...string) (
 	return bufOut.String(), bufErr.String(), err
 }
 
-// Exec starts executing a command, it records its process and timeout.
+// ExecTimeout runs a command and waits for its completion
+// up to the given timeout (or DefaultTimeout if -1 is given).
+// Returns its complete stdout and stderr
+// outputs and an error, if any (including timeout)
 func ExecTimeout(timeout time.Duration, desc, cmdName string, args ...string) (string, string, error) {
 	return ExecDir(timeout, "", desc, cmdName, args...)
 }
 
-// Exec starts executing a command, it records its process and has default timeout.
+// Exec runs a command and waits for its completion
+// up to DefaultTimeout. Returns its complete stdout and stderr
+// outputs and an error, if any (including timeout)
 func Exec(desc, cmdName string, args ...string) (string, string, error) {
 	return ExecDir(-1, "", desc, cmdName, args...)
 }