From 18771b6ae823c761de225332eae107e18b1683ee Mon Sep 17 00:00:00 2001
From: M0Rf30 <morf3089@gmail.com>
Date: Sat, 21 Oct 2023 18:14:25 +0200
Subject: [PATCH] documentation

---
 pkg/options/strip.go     |  3 +++
 pkg/packer/packer.go     | 13 +++++++++++++
 pkg/pkgbuild/pkgbuild.go |  9 +++++++++
 pkg/source/source.go     |  2 ++
 4 files changed, 27 insertions(+)

diff --git a/pkg/options/strip.go b/pkg/options/strip.go
index 436a954..8526edc 100644
--- a/pkg/options/strip.go
+++ b/pkg/options/strip.go
@@ -1,5 +1,8 @@
 package options
 
+// StripScript is a scriptlet taken from makepkg resources.
+// It's executed by mvdan/sh interpreter and provides strip instructions to dpkg-buildpackage.
+// Although it's a very dirty solution, for now it's the faster way to have this essential feature.
 const StripScript = `
 strip_file() {
 	local binary=$1; shift
diff --git a/pkg/packer/packer.go b/pkg/packer/packer.go
index c02cbf8..82b9191 100644
--- a/pkg/packer/packer.go
+++ b/pkg/packer/packer.go
@@ -12,14 +12,27 @@ import (
 	"github.com/M0Rf30/yap/pkg/redhat"
 )
 
+// Packer is the common interface implemented by all package managers.
 type Packer interface {
+	// Prepare appends the dependencies required to build all the projects.
+	// It returns any error if encountered.
 	Prepare(depends []string) error
+	// Build reads the path where the final artifact will be written.
+	// It returns any error if encountered.
 	Build(output string) error
+	// Install reads the path where the final artifact will be written.
+	// It returns any error if encountered.
 	Install(output string) error
+	// PrepareEnvironment reads a flag to install golang tools on request, on the build machine.
+	// It returns any error if encountered.
 	PrepareEnvironment(flag bool) error
+	// Update performs a package manager update operation.
+	// It returns any error if encountered.
 	Update() error
 }
 
+// GetPackageManager reads the pkgBuild structure and the distro name.
+// It returns a Packer interface representing the specialized package manager for that distro.
 func GetPackageManager(pkgBuild *pkgbuild.PKGBUILD, distro string) Packer {
 	var packageManager Packer
 
diff --git a/pkg/pkgbuild/pkgbuild.go b/pkg/pkgbuild/pkgbuild.go
index dfe0e61..ccc70fb 100644
--- a/pkg/pkgbuild/pkgbuild.go
+++ b/pkg/pkgbuild/pkgbuild.go
@@ -16,6 +16,8 @@ import (
 
 var Verbose bool
 
+// PKGBUILD defines all the fields accepted by the yap specfile (variables, arrays, functions).
+// It adds some exotics fields to manage debconfig templating and other rpm/deb descriptors.
 type PKGBUILD struct {
 	Arch           []string
 	Backup         []string
@@ -61,6 +63,10 @@ type PKGBUILD struct {
 	priorities     map[string]int
 }
 
+// AddItem reads a key and the related data.
+// It checks the key for __ token and give to it a priority value.
+// After that binds every element (variable, array, funtion) to the current environment.
+// It returns any error if encountered.
 func (pkgBuild *PKGBUILD) AddItem(key string, data any) error {
 	key, priority, err := pkgBuild.parseDirective(key)
 	if err != nil {
@@ -270,6 +276,9 @@ func (pkgBuild *PKGBUILD) mapVariables(key string, data any) {
 	}
 }
 
+// parseDirective reads a directive string and detect any specialized one (i.e only to be applied for ubuntu).
+// It detects if distro codename is given and calculates and assigns a priority to the directive.
+// It returns the directive key, assigned priority and any error if occurred.
 func (pkgBuild *PKGBUILD) parseDirective(input string) (string, int, error) {
 	split := strings.Split(input, "__")
 	key := split[0]
diff --git a/pkg/source/source.go b/pkg/source/source.go
index 6814d0d..43d9544 100644
--- a/pkg/source/source.go
+++ b/pkg/source/source.go
@@ -192,6 +192,8 @@ func (src *Source) symlinkSources() error {
 	return err
 }
 
+// validate checks that items declared in the source array
+// have a valid hashsum. It returns any error encountered.
 func (src *Source) validate() error {
 	info, err := os.Stat(filepath.Join(src.StartDir, src.SourceItemPath))
 	if err != nil {