[DOC] add godoc comments

README.md

@@ -1,20 +1,20 @@
 # Stock-Microservice
 This is a microservice cutted out of a [Monolith](https://gitlab.com/matthiasstock/monolith).
 
-[![Build Status](https://travis-ci.org/genofire/hs_master-kss-monolith.svg?branch=master)](https://travis-ci.org/genofire/hs_master-kss-monolith)  [![Coverage Status](https://coveralls.io/repos/github/genofire/hs_master-kss-monolith/badge.svg?branch=master)](https://coveralls.io/github/genofire/hs_master-kss-monolith?branch=master)
+[![Build Status](https://travis-ci.org/genofire/hs_master-kss-monolith.svg?branch=master)](https://travis-ci.org/genofire/hs_master-kss-monolith)  [![Coverage Status](https://coveralls.io/repos/github/genofire/hs_master-kss-monolith/badge.svg?branch=master)](https://coveralls.io/github/genofire/hs_master-kss-monolith?branch=master) [![GoDoc](https://godoc.org/github.com/genofire/hs_master-kss-monolith?status.svg)](https://godoc.org/github.com/genofire/hs_master-kss-monolith)
 
 ## Features of this stock mircoservice
 * The main functionality of the microservice is to store the goods with their storage location and a time stamp, when they where stored.
 * Functionality of the admin frontend
-** Add new goods to the stock
-** Manually remove a single goods from the stock, for example when they are rancid
-** Remove single goods from the stock, when they are send to a costumer
-** Block goods from the stock, when a costumer added them to hie cart
+  * Add new goods to the stock
+  * Manually remove a single goods from the stock, for example when they are rancid
+  * Remove single goods from the stock, when they are send to a costumer
+  * Block goods from the stock, when a costumer added them to hie cart
 * Functionality of the costumer frontend
-** Show the store with a traffic light food labelling
-** A stock of more then seven goods corresponds to the colour green (sufficient amount of goods)
-** A stock between four and seven goods corresponds to the colour orange (moderate amount of goods)
-** A stock between zero and three goods corresponds to the colour red (slim amount of goods)
+  * Show the store with a traffic light food labelling
+  * A stock of more then seven goods corresponds to the colour green (sufficient amount of goods)
+  * A stock between four and seven goods corresponds to the colour orange (moderate amount of goods)
+  * A stock between zero and three goods corresponds to the colour red (slim amount of goods)
 * Optional Features
-** Admin frontend: display of a statistic on how many goods where convexed and manually removed from the stock during the last month
-** Traffic light food labelling for each good, which indicates whether the good is too old
+  * Admin frontend: display of a statistic on how many goods where convexed and manually removed from the stock during the last month
+  * Traffic light food labelling for each good, which indicates whether the good is too old

cmd/stock/main.go

@@ -1,3 +1,4 @@
+// The cmd binary of the microservice to run
 package main
 
 import (

http/bindapi.go

@@ -1,3 +1,4 @@
+// all api routes of this microservice
 package http
 
 import (
@@ -5,6 +6,7 @@ import (
 	"goji.io/pat"
 )
 
+// bind all API routes to webserver
 func BindAPI(router *goji.Mux) {
 	router.HandleFunc(pat.Get("/api/status"), status)
 	router.HandleFunc(pat.Get("/api/good/:productid"), listGoods)

http/good_temp.go

@@ -8,6 +8,7 @@ import (
 	"text/template"
 )
 
+// path to the svg image templaes to show availablity of a given good
 var GoodAvailablityTemplate string
 
 func tempProcent(value, max int) int {

lib/database/database.go

@@ -10,18 +10,28 @@ import (
 	"github.com/genofire/hs_master-kss-monolith/lib/log"
 )
 
+// Database connection for writing
+var Write *gorm.DB
+
+// Database connection for reading
+var Read *gorm.DB
+
 var (
-	Write  *gorm.DB
-	Read   *gorm.DB
-	config *Config
+	config  *Config
 	runtime []interface{}
 )
 
+// configuration for the database connection
 type Config struct {
-	Type           string
-	Connection     string
+	// type of database: current support sqlite and postgres
+	// (by request other could be enabled)
+	Type string
+	// connection configuration
+	Connection string
+	// maybe create another connection just for reading
 	ReadConnection string
-	Logging        bool
+	// enable logging the generated sql string
+	Logging bool
 }
 
 // Function to open a database and set the given configuration
@@ -56,7 +66,7 @@ func Open(c Config) (err error) {
 	return
 }
 
-//Function to safely close the database
+// Function to safely close the database
 func Close() {
 	Write.Close()
 	Write = nil

lib/http/permission.go

@@ -4,9 +4,10 @@ package http
 
 import "net/http"
 
+// format of a function to bind it for the middleware handler
 type HasPermission func(string, int) (bool, error)
 
-//Function to evaluate the permission and implent an error handling
+// Function to evaluate the permission and implent an error handling
 // Input: http response writer w, pointer to htto request r, bool variable HasPermission perm, int variable permission (form)
 func PermissionHandler(h func(w http.ResponseWriter, r *http.Request), perm HasPermission, permission int) func(w http.ResponseWriter, r *http.Request) {
 	return func(w http.ResponseWriter, r *http.Request) {

lib/log/log.go

@@ -9,10 +9,9 @@ import (
 	logger "github.com/Sirupsen/logrus"
 )
 
+// current logger with configuration
 var Log *logger.Logger
 
-type Logger logger.Entry
-
 // Function to initiate a new logger
 func init() {
 	Log = logger.New()

lib/worker/worker.go

@@ -1,13 +1,16 @@
+// A little lib for cronjobs to run it in background
 package worker
 
 import "time"
 
+// a struct which handle the job
 type Worker struct {
 	every time.Duration
 	run   func()
 	quit  chan struct{}
 }
 
+// create a new Worker with timestamp run every and his function
 func NewWorker(every time.Duration, f func()) (w *Worker) {
 	w = &Worker{
 		every: every,
@@ -17,6 +20,8 @@ func NewWorker(every time.Duration, f func()) (w *Worker) {
 	return
 }
 
+// start the worker
+// please us it as a goroutine: go w.Start()
 func (w *Worker) Start() {
 	ticker := time.NewTicker(w.every)
 	for {
@@ -29,6 +34,8 @@ func (w *Worker) Start() {
 		}
 	}
 }
+
+// stop the worker
 func (w *Worker) Close() {
 	close(w.quit)
 }

models/config.go

@@ -9,31 +9,45 @@ import (
 	"github.com/genofire/hs_master-kss-monolith/lib/log"
 )
 
-//Config the config File of this daemon
+//config file of this daemon (for more the config_example.conf in git repository)
 type Config struct {
-	WebserverBind            string            `toml:"webserver_bind"`
-	Webroot                  string            `toml:"webroot"`
-	Database                 database.Config   `toml:"database"`
-	GoodRelease              GoodReleaseConfig `toml:"good_release"`
-	CacheClean               CacheWorkerConfig `toml:"cache_clean"`
-	GoodAvailablityTemplate  string            `toml:"good_availablity_template"`
+	// address on which the api and static content webserver runs
+	WebserverBind string `toml:"webserver_bind"`
+
+	// path to deliver static content
+	Webroot string `toml:"webroot"`
+
+	Database    database.Config   `toml:"database"`
+	GoodRelease GoodReleaseConfig `toml:"good_release"`
+	CacheClean  CacheWorkerConfig `toml:"cache_clean"`
+
+	// path to the svg image templaes to show availablity of a given good
+	GoodAvailablityTemplate string `toml:"good_availablity_template"`
+
+	// URLs to other microservices
 	MicroserviceDependencies struct {
 		Product    string `toml:"product"`
 		Permission string `toml:"permission"`
 	} `toml:"microservice_dependencies"`
 }
 
+//config of worker to clean caches from values of other microservice
 type CacheWorkerConfig struct {
+	// run worker every ...
 	Every Duration
+	// remove cache which is not used since ..
 	After Duration
 }
 
+//config of worker to release looked goods after a time
 type GoodReleaseConfig struct {
-	After Duration `toml:"after"`
+	// run worker every ...
 	Every Duration `toml:"every"`
+	// unlock which is not used since ..
+	After Duration `toml:"after"`
 }
 
-// ReadConfigFile reads a config model from path of a yml file
+//reads a config model from path of a yml file
 func ReadConfigFile(path string) *Config {
 	config := &Config{}
 	file, err := ioutil.ReadFile(path)

models/good.go

@@ -9,6 +9,7 @@ import (
 	"github.com/genofire/hs_master-kss-monolith/lib/database"
 )
 
+// this stock microservice manage goods
 type Good struct {
 	ID        int64
 	ProductID int64
@@ -25,18 +26,24 @@ type Good struct {
 	Sended    bool
 }
 
+// generate database select which filtered locked goods
 func (g *Good) FilterAvailable(db *gorm.DB) *gorm.DB {
 	return db.Model(g).Where("locked_secret == '' OR locked_secret is NULL")
 }
 
+// lock the good, on a way, that it could not be used by other users
 func (g *Good) Lock(secret string) {
 	now := time.Now()
 	g.LockedSecret = secret
 	g.LockedAt = &now
 }
+
+// is this good locked?
 func (g *Good) IsLock() bool {
 	return len(g.LockedSecret) > 0
 }
+
+// unlock the good, that it could be usered again
 func (g *Good) Unlock(secret string) error {
 	if g.LockedSecret == secret {
 		g.LockedSecret = ""

models/main.go

@@ -0,0 +1,2 @@
+// a package to store all the struct
+package models

runtime/auth.go

@@ -8,12 +8,19 @@ import (
 	"github.com/genofire/hs_master-kss-monolith/lib/log"
 )
 
+// url to the microservice which manage the permissions
 var PermissionURL string
 
+// type of permission
 type Permission int
 
+// some permission (see Permission)
 const (
+	// has the user the permission to create need goods of a product
+	// e.g. if a good received and now availablity to sell
 	PermissionCreateGood = 1
+	// has the user the permission to delete need goods of a product
+	// e.g. if a good become rancid and has to remove from stock
 	PermissionDeleteGood = 2
 )
 
@@ -49,6 +56,7 @@ func init() {
 	permissionCache = make(map[string]*permissionMicroServiceCache)
 }
 
+// check if the client with the session string has a permissions (see Permission)
 func HasPermission(session string, p Permission) (bool, error) {
 	_, ok := permissionCache[session]
 	if !ok {

runtime/cache_worker.go

@@ -7,8 +7,10 @@ import (
 	"github.com/genofire/hs_master-kss-monolith/models"
 )
 
+// config of the cache worker
 var CacheConfig models.CacheWorkerConfig
 
+// command which is runned in the cache worker
 func CleanCache() {
 	before := time.Now().Add(-CacheConfig.After.Duration)
 	// Cache if product exists
@@ -24,6 +26,8 @@ func CleanCache() {
 		}
 	}
 }
+
+// create a worker to clean the caches which stored from other microservice
 func NewCacheWorker() (w *worker.Worker) {
 	return worker.NewWorker(CacheConfig.Every.Duration, CleanCache)
 }

runtime/good_release.go

@@ -8,6 +8,7 @@ import (
 	"github.com/genofire/hs_master-kss-monolith/models"
 )
 
+// create a worker to unlock goods which are locked by clients
 func NewGoodReleaseWorker(grc models.GoodReleaseConfig) *worker.Worker {
 	return worker.NewWorker(grc.Every.Duration, func() {
 		goodRelease(grc.After.Duration)

runtime/main.go

@@ -0,0 +1,2 @@
+// some functionality to handle it in background which is intermeshed
+package runtime

runtime/productcache.go

@@ -8,6 +8,7 @@ import (
 	"github.com/genofire/hs_master-kss-monolith/lib/log"
 )
 
+// url to the microservice which manage the products
 var ProductURL string
 
 type boolMicroServiceCache struct {
@@ -21,6 +22,7 @@ func init() {
 	productExistCache = make(map[int64]boolMicroServiceCache)
 }
 
+// check on the other microservice if the product exists
 func ProductExists(id int64) (bool, error) {
 	if cache, ok := productExistCache[id]; ok {
 		return cache.Value, nil

test/testrest.go

@@ -1,3 +1,4 @@
+// A little lib to easy create everything for running virtual api
 package test
 
 // Request an easy manager to test REST-API
@@ -16,7 +17,7 @@ import (
 
 var srv *http.Server
 
-//Init to initialisieren an API
+//initialisieren an API test api
 func Init(t *testing.T) (assertion *assert.Assertions, router *goji.Mux) {
 	assertion = assert.New(t)
 	database.Open(database.Config{
@@ -35,15 +36,18 @@ func Init(t *testing.T) (assertion *assert.Assertions, router *goji.Mux) {
 	return
 }
 
+// close just the static webserver (with test files of other microservice)
 func CloseServer() {
 	srv.Close()
 }
 
+// close everything
 func Close() {
 	database.Close()
 	srv.Close()
 }
 
+// handle a test client session with cookies
 type Request struct {
 	req     *http.Request
 	cookies []*http.Cookie
@@ -55,7 +59,7 @@ func NewSession(router *goji.Mux) *Request {
 	return &Request{router: router}
 }
 
-// JSONRequest send request to router
+// send request to router and recieve the api answer
 func (r *Request) JSONRequest(method string, url string, body interface{}) (jsonResult interface{}, res *http.Response) {
 	jsonObj, _ := json.Marshal(body)
 	req, _ := http.NewRequest(method, url, bytes.NewReader(jsonObj))
@@ -75,7 +79,7 @@ func (r *Request) JSONRequest(method string, url string, body interface{}) (json
 	return
 }
 
-// Clean to clean the current session
+// clean the current session
 func (r *Request) Clean() {
 	r.cookies = nil
 }