Add documentation

Tools/FormatTime.go

@@ -6,6 +6,7 @@ import (
 	"time"
 )
 
+// Formats the given time as YYYYMMdd HHmmss.fff
 func FormatTime(t1 time.Time) (result string) {
 	var year int = t1.Year()
 	var month int = int(t1.Month())

Tools/Hostname.go

@@ -1,5 +1,6 @@
 package Tools
 
+// Provide the server's hostname.
 func ThisHostname() (result string) {
 	result = hostname
 	return

Tools/IPAddresses.go

@@ -5,14 +5,19 @@ import (
 	"strings"
 )
 
+// Provides all IP addresses for this server.
 func ReadAllIPAddresses4ThisHost() (addresses4Host []string) {
 	addresses4Host = ipAddresses
 	return
 }
 
+// Read all IP addreses once.
 func initIPAddresses4ThisHost() {
+
+	// Get any IP addresses:
 	addresses, err := net.InterfaceAddrs()
 	if err != nil {
+		// Case: Error! Use localhost.
 		ipAddresses = make([]string, 1)
 		ipAddresses[0] = `127.0.0.1`
 		return
@@ -20,13 +25,21 @@ func initIPAddresses4ThisHost() {
 
 	counter := 0
 	ipAddresses = make([]string, len(addresses))
+
+	// Loop over all addresses:
 	for _, address := range addresses {
 		addressText := address.String()
+
+		// Case: CIDR notation?
 		if strings.Contains(addressText, `/`) {
+			// Convert the address:
 			addressText = addressText[:strings.Index(addressText, `/`)]
 		}
 
+		// Parse the address to determine some meta data:
 		ip := net.ParseIP(addressText)
+
+		// Filter out any loopback and local entries:
 		if !ip.IsLoopback() && !ip.IsUnspecified() && strings.ToLower(ip.String()) != `fe80::1` {
 			ipAddresses[counter] = ip.String()
 			counter++
@@ -34,6 +47,8 @@ func initIPAddresses4ThisHost() {
 	}
 
 	if counter == 0 {
+		// Case: No public facing address found.
+		// Use localhost instead.
 		ipAddresses = make([]string, 1)
 		ipAddresses[0] = `127.0.0.1`
 	} else {

Tools/Init.go

@@ -12,7 +12,7 @@ import (
 )
 
 func init() {
-	// Get this hostname:
+	// Get the hostname of this server:
 	if hostText, errHost := os.Hostname(); errHost != nil {
 		panic(`Was not able to read the hostname: ` + errHost.Error())
 	} else {
@@ -40,6 +40,6 @@ func init() {
 		localIPAddressAndPort = fmt.Sprintf("%s:%s", allHostsIPAddresses[0], port)
 	}
 
-	// Read the default language:
+	// Read the default language for I18N:
 	defaultLanguage = ConfigurationDB.Read(`DefaultLanguageCode`)
 }

Tools/InternalCommPassword.go

@@ -1,5 +1,6 @@
 package Tools
 
+// Provides the communication password.
 func InternalCommPassword() (pwd string) {
 	pwd = internalCommPassword
 	return

Tools/LocalIPAddressAndPort.go

@@ -1,5 +1,6 @@
 package Tools
 
+// Returns the own (thus: local) public facing IP address with port.
 func LocalIPAddressAndPort() (address string) {
 	address = localIPAddressAndPort
 	return

Tools/Random.go

@@ -5,11 +5,13 @@ import (
 	"math/rand"
 )
 
+// Gets a random integer between 0 and max-1.
 func RandomInteger(max int) (rnd int) {
 	rnd = rand.Intn(max)
 	return
 }
 
+// Gets a random UUID (v4).
 func RandomGUID() (guidString string) {
 	guidString = uuid.NewV4().String()
 	guidString = guidString[1 : len(guidString)-1]

Tools/RequestLanguage.go

@@ -7,44 +7,63 @@ import (
 	"strings"
 )
 
+// Gets the language of a request for enable I18N.
 func GetRequestLanguage(request *http.Request) (resultLangs Languages) {
+
+	// Read the goven data from the request:
 	languageCodeForm := request.FormValue(`lang`)
 	languageCodeHeader := request.Header.Get(`Accept-Language`)
 
+	// Is only one language available?
 	if languageCodeForm != `` && ((len(languageCodeForm) == 2) || (len(languageCodeForm) == 5 && strings.Contains(languageCodeForm, `-`))) {
+
+		// Case: Only one language available.
 		resultLangs = make(Languages, 1)
 		resultLangs[0].Factor = 1.0
 		resultLangs[0].Language = strings.ToLower(languageCodeForm)
 		return
 	}
 
+	// Case: The Accept-Language fild is empty.
 	if languageCodeHeader == `` {
+		// Use the default language:
 		resultLangs = make(Languages, 1)
 		resultLangs[0].Factor = 1.0
 		resultLangs[0].Language = defaultLanguage
 		return
 	}
 
+	// Separate each language:
 	values := strings.Split(languageCodeHeader, `,`)
 	langs := make(Languages, len(values))
+
+	// Loop over all languages:
 	for n, langData := range values {
+
+		// Is the factor given?
 		if factorData := strings.Split(langData, `;q=`); len(factorData) == 2 {
+
+			// Try to parse the factor:
 			if factor, errFactor := strconv.ParseFloat(factorData[1], 32); errFactor != nil {
+				// Case: Parsing was not possible. Use 1 instead:
 				langs[n] = Language{}
 				langs[n].Language = strings.ToLower(strings.Trim(factorData[0], ` `))
 				langs[n].Factor = 1.0
 			} else {
+				// Case: Factor was parsed.
 				langs[n] = Language{}
 				langs[n].Language = strings.ToLower(strings.Trim(factorData[0], ` `))
 				langs[n].Factor = float32(factor)
 			}
 		} else {
+			// Case: No factor given. Use 1 instead.
 			langs[n] = Language{}
 			langs[n].Language = strings.ToLower(strings.Trim(langData, ` `))
 			langs[n].Factor = 1.0
 		}
 	}
 
+	// Sort all languages by factor:
 	sort.Sort(langs)
 	resultLangs = langs
 	return

Tools/ResponseLanguage.go

@@ -4,6 +4,7 @@ import (
 	"net/http"
 )
 
+// Send the chosen language for the content.
 func SendChosenLanguage(response http.ResponseWriter, lang Language) {
 	response.Header().Add(`Content-Language`, lang.Language)
 }

Tools/SchemeLanguage.go

@@ -1,20 +1,25 @@
 package Tools
 
+// The data type for the language.
 type Language struct {
 	Language string
 	Factor   float32
 }
 
+// The data type for multiple languages.
 type Languages []Language
 
+// Ensure, that the languages are sortable.
 func (lang Languages) Len() int {
 	return len(lang)
 }
 
+// Ensure, that the languages are sortable.
 func (lang Languages) Less(i, j int) bool {
 	return lang[i].Factor > lang[j].Factor
 }
 
+// Ensure, that the languages are sortable.
 func (lang Languages) Swap(i, j int) {
 	lang[i], lang[j] = lang[j], lang[i]
 }

Tools/Variables.go

@@ -5,10 +5,10 @@ import (
 )
 
 var (
-	senderName            LM.Sender = `System::Tools`
-	hostname              string    = `unknown`
-	localIPAddressAndPort string    = `127.0.0.1:60000`
-	ipAddresses           []string  = nil
-	internalCommPassword  string    = ``
-	defaultLanguage       string    = `en`
+	senderName            LM.Sender = `System::Tools`   // This is the name for logging event from this package
+	hostname              string    = `unknown`         // The local server's hostname
+	localIPAddressAndPort string    = `127.0.0.1:60000` // The local server's IP address and port
+	ipAddresses           []string  = nil               // All public IP addresses of this server
+	internalCommPassword  string    = ``                // The communication password
+	defaultLanguage       string    = `en`              // The default language for I18N
 )