Add documentation

cmd/api/handlers.go

@@ -11,6 +11,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// handlers is the main struct for handling endpoints
 type handlers struct {
 	log logger.Logger
 	db  database.Database

cmd/api/main.go

@@ -18,6 +18,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// FizzBuzz represents the main structure
 type FizzBuzz struct {
 	engine *gin.Engine
 	srv    *http.Server
@@ -27,6 +28,7 @@ type FizzBuzz struct {
 	quit chan os.Signal
 }
 
+// setupRouter init the main structure and the http router as well
 func setupRouter() (fb *FizzBuzz, err error) {
 	l := logrus.NewLogrusLogger()
 	_, isDebug := os.LookupEnv("DEBUG")
@@ -44,6 +46,8 @@ func setupRouter() (fb *FizzBuzz, err error) {
 	return fb, nil
 }
 
+// Run will run main program along the http server.
+// It should be run as goroutine and stopped using Stop function
 func (fb *FizzBuzz) Run(port string) {
 	fb.srv = &http.Server{
 		Addr:    fmt.Sprintf(":%s", port),
@@ -57,6 +61,7 @@ func (fb *FizzBuzz) Run(port string) {
 	}
 }
 
+// Stop is used to stop the main program and its http server properly
 func (fb FizzBuzz) Stop() {
 	fb.log.Warn("stop signal catched, closing server")
 
@@ -71,6 +76,8 @@ func (fb FizzBuzz) Stop() {
 	fb.log.Info("server closed, exiting")
 }
 
+// initRoutes is used to init the base routes and attach them
+// to the router
 func initRoutes(fb *FizzBuzz, db database.Database) {
 	h := handlers{
 		log: fb.log,

pkg/database/mysql/database.go

@@ -21,6 +21,7 @@ type MySQLDatabase struct {
 	db *gorm.DB
 }
 
+// InitDatabase is used to return the MySQL database instance
 func InitDatabase() (*MySQLDatabase, error) {
 	dbHost := os.Getenv(MYSQL_HOST)
 	dbDatabase := os.Getenv(MYSQL_DB)
@@ -45,12 +46,15 @@ func InitDatabase() (*MySQLDatabase, error) {
 	}, err
 }
 
+// CountUsage is used to return the number of usages of FizzBuzz from the DB
 func (db *MySQLDatabase) CountUsage() (models.Stats, error) {
 	var result []models.Stats
 
 	err := db.db.Model(&models.Stats{}).Find(&result).Error
 
 	// @TODO: use max() instead
+	// reason of the comment : encountered a library bug with the driver
+	// getting every entries is usually a bad practice
 	var mostUsed models.Stats
 	for _, stat := range result {
 		if stat.Use > mostUsed.Use {
@@ -61,6 +65,8 @@ func (db *MySQLDatabase) CountUsage() (models.Stats, error) {
 	return mostUsed, err
 }
 
+// UsageUpdate is used to increment the number of usages for FizzBuzz endpoint
+// to the database
 func (db *MySQLDatabase) UsageUpdate(m models.Stats) error {
 	return db.db.Transaction(func(tx *gorm.DB) error {
 		var result models.Stats

pkg/models/stats.go

@@ -4,6 +4,8 @@ import (
 	"gorm.io/gorm"
 )
 
+// Stats is the model to store FizzBuzz calls and
+// the numbers of usages
 type Stats struct {
 	gorm.Model