Merge pull request #22 from Beebeeoii/documentations

added documentations

internal/app/app.go

@@ -1,3 +1,4 @@
+// Package app provides primitives to initialise crucial files for Lominus.
 package app
 
 import (
@@ -13,6 +14,9 @@ import (
 	"github.com/beebeeoii/lominus/pkg/pref"
 )
 
+// Init initialises and ensures log and preference files that Lominus requires are available.
+// Directory in Preferences defaults to empty string ("").
+// Frequency in Preferences defaults to -1.
 func Init() error {
 	baseDir := appDir.GetBaseDir()
 
@@ -39,6 +43,9 @@ func Init() error {
 	return nil
 }
 
+// GetOs returns user's running program's operating system target:
+// one of darwin, freebsd, linux, and so on.
+// To view possible combinations of GOOS and GOARCH, run "go tool dist list".
 func GetOs() string {
 	return runtime.GOOS
 }

internal/app/auth/auth.go

@@ -1,3 +1,4 @@
+// Package appAuth provides path retrievers for Lominus auth files.
 package appAuth
 
 import (
@@ -7,10 +8,12 @@ import (
 	"github.com/beebeeoii/lominus/internal/lominus"
 )
 
+// GetJwtPath returns the file path to user's JWT data.
 func GetJwtPath() string {
 	return filepath.Join(appDir.GetBaseDir(), lominus.JWT_DATA_FILE_NAME)
 }
 
+// GetJwtPath returns the file path to user's credentials.
 func GetCredentialsPath() string {
 	return filepath.Join(appDir.GetBaseDir(), lominus.CREDENTIALS_FILE_NAME)
 }

internal/app/dir/dir.go

@@ -1,3 +1,4 @@
+// Package appDir provides directory generators for Lominus config files.
 package appDir
 
 import (
@@ -8,6 +9,13 @@ import (
 	"github.com/beebeeoii/lominus/internal/lominus"
 )
 
+// GetBaseDir returns the directory where config files for Lominus will be stored in.
+// It uses os.UserConfigDir() under the hood and appends lominus.APP_NAME to it.
+// On Unix systems, os.UserConfigDir() returns $XDG_CONFIG_HOME as specified by https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+// if non-empty, else $HOME/.config.
+// On Darwin, it returns $HOME/Library/Application Support.
+// On Windows, it returns %AppData%. On Plan 9, it returns $home/lib.
+// If the location cannot be determined (for example, $HOME is not defined), then it will return an error.
 func GetBaseDir() string {
 	userConfigDir, err := os.UserConfigDir()
 	if err != nil {

internal/app/integrations/telegram/telegram.go

@@ -1,3 +1,4 @@
+// Package intTelegram provides path retrievers for Lominus Telegram integration files.
 package intTelegram
 
 import (
@@ -7,6 +8,7 @@ import (
 	"github.com/beebeeoii/lominus/internal/lominus"
 )
 
+// GetTelegramInfoPath returns the file path to user's telegram config file.
 func GetTelegramInfoPath() string {
 	return filepath.Join(appDir.GetBaseDir(), lominus.TELEGRAM_FILE_NAME)
 }

internal/app/lock/lock.go

@@ -1,3 +1,4 @@
+// Package appLock provides path retrievers for Lominus lock file.
 package appLock
 
 import (
@@ -7,6 +8,7 @@ import (
 	"github.com/beebeeoii/lominus/internal/lominus"
 )
 
+// GetLockPath returns the file path to Lominus lock file.
 func GetLockPath() string {
 	return filepath.Join(appDir.GetBaseDir(), lominus.LOCK_FILE_NAME)
 }

internal/app/pref/pref.go

@@ -1,3 +1,4 @@
+// Package appPref provides path retrievers for Lominus preferences files.
 package appPref
 
 import (
@@ -7,11 +8,13 @@ import (
 	"github.com/beebeeoii/lominus/internal/lominus"
 )
 
+// Preferences struct describes the data being stored in the user's preferences file.
 type Preferences struct {
 	Directory string
 	Frequency int
 }
 
+// GetJwtPath returns the file path to user's preferences.
 func GetPreferencesPath() string {
 	return filepath.Join(appDir.GetBaseDir(), lominus.PREFERENCES_FILE_NAME)
 }

internal/cron/cron.go

@@ -1,3 +1,4 @@
+// Package cron provides primitives to initialise and control the main cron scheduler.
 package cron
 
 import (
@@ -23,6 +24,8 @@ var mainScheduler *gocron.Scheduler
 var mainJob *gocron.Job
 var LastRanChannel chan string
 
+// Init initialises the cronjob with the desired frequency set by the user.
+// If frequency is unset, cronjob is not initialised.
 func Init() error {
 	mainScheduler = gocron.NewScheduler(time.Local)
 	LastRanChannel = make(chan string)
@@ -47,6 +50,7 @@ func Init() error {
 	return nil
 }
 
+// Rerun clears the job from the scheduler and reschedules the same job with the new frequency.
 func Rerun(frequency int) error {
 	mainScheduler.Clear()
 
@@ -65,14 +69,19 @@ func Rerun(frequency int) error {
 	return nil
 }
 
+// GetNextRun returns the next time the cronjob would run.
 func GetNextRun() time.Time {
 	return mainJob.NextRun()
 }
 
+// GetLastRan returns the last time the cronjob ran.
 func GetLastRan() time.Time {
 	return mainJob.LastRun()
 }
 
+// createJob creates the cronjob that would run at the given frequency.
+// It returns a Job which can be used in the main scheduler.
+// This is where the bulk of the syncing logic lives.
 func createJob(frequency int) (*gocron.Job, error) {
 	return mainScheduler.Every(frequency).Hours().Do(func() {
 		notifications.NotificationChannel <- notifications.Notification{Title: "Sync", Content: "Syncing in progress"}
@@ -208,6 +217,8 @@ func createJob(frequency int) (*gocron.Job, error) {
 	})
 }
 
+// downloadFile is a helper function to download the respective files into their corresponding
+// directory based on the File's Ancestors.
 func downloadFile(baseDir string, file api.File) error {
 	fileDirSlice := append([]string{baseDir}, file.Ancestors...)
 	ensureDir(filepath.Join(append(fileDirSlice, file.Name)...))
@@ -220,6 +231,8 @@ func downloadFile(baseDir string, file api.File) error {
 	return downloadReq.Download(filepath.Join(fileDirSlice...))
 }
 
+// ensureDir is a helper function that ensures that the directory exists by creating them
+// if they do not already exist.
 func ensureDir(dir string) {
 	dirName := filepath.Dir(dir)
 	if _, serr := os.Stat(dirName); serr != nil {

internal/file/file.go

@@ -1,3 +1,4 @@
+// Package file provides util primitives to file operations.
 package file
 
 import (
@@ -6,6 +7,10 @@ import (
 	"os"
 )
 
+// EncodeStructToFile takes in any struct and encodes it into a file specified by fileName.
+// If the file already exists, it is truncated.
+// If the file does not exist, it is created with mode 0666 (before umask).
+// Provide absolute path else file will be written to the current working directory.
 func EncodeStructToFile(fileName string, data interface{}) error {
 	file, err := os.Create(fileName)
 	if err != nil {
@@ -20,6 +25,8 @@ func EncodeStructToFile(fileName string, data interface{}) error {
 	return nil
 }
 
+// DecodeStructFromFile takes a file that has been encoded by a struct and decodes it back to the struct.
+// Provide absolute path else file may not be found.
 func DecodeStructFromFile(fileName string, data interface{}) error {
 	file, err := os.Open(fileName)
 	if err != nil {
@@ -32,16 +39,19 @@ func DecodeStructFromFile(fileName string, data interface{}) error {
 	return err
 }
 
+// Exists checks if the given file exists.
 func Exists(name string) bool {
 	_, err := os.Stat(name)
 
 	return err == nil
 }
 
+// FileNotFoundError struct is an error struct that contains the custom error that will be thrown when file is not found.
 type FileNotFoundError struct {
 	FileName string
 }
 
+// FileNotFoundError is an error that will be thrown when file is not found.
 func (e *FileNotFoundError) Error() string {
 	return fmt.Sprintf("FileNotFoundError: %s cannot be found.", e.FileName)
 }

internal/indexing/indexing.go

@@ -1,3 +1,4 @@
+// Package file provides primitives to file indexing for sync operations.
 package indexing
 
 import (
@@ -13,10 +14,14 @@ import (
 	"github.com/beebeeoii/lominus/pkg/api"
 )
 
+// IndexMap struct contains an array of IndexMapEntry.
+// It is used to create a .csv IndexMap file for file comparison during syncs.
 type IndexMap struct {
 	Entries []IndexMapEntry
 }
 
+// IndexMapEntry struct contains the file Id, name and last updated (unix).
+// These are the data used for file comparison during syncs.
 type IndexMapEntry struct {
 	Id          string
 	FileName    string
@@ -25,6 +30,9 @@ type IndexMapEntry struct {
 
 const INDEX_MAP_FILE_NAME = "index_map.csv"
 
+// Build is used to create a map of the current files on the local desktop.
+// The built map will be used to compare with the IndexMap to determine whether a file
+// needs to be downloaded or updated.
 func Build(dir string) (map[string]api.File, error) {
 	filesMap := make(map[string]api.File)
 	err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
@@ -49,6 +57,7 @@ func Build(dir string) (map[string]api.File, error) {
 	return filesMap, err
 }
 
+// CreateIndexMap writes the IndexMap to a csv file for which can be loaded for the next sync.
 func CreateIndexMap(indexMap IndexMap) error {
 	logs.InfoLogger.Printf("Creating index map: %s\n", INDEX_MAP_FILE_NAME)
 	indexMapFile, _ := os.Create(getIndexMapPath())
@@ -66,6 +75,7 @@ func CreateIndexMap(indexMap IndexMap) error {
 	return nil
 }
 
+// LoadIndexMap loads the IndexMap csv file back to a map of IndexMapEntry, with the key being the file Id.
 func LoadIndexMap(file io.Reader) (map[string]IndexMapEntry, error) {
 	logs.InfoLogger.Printf("Loading index map: %s\n", INDEX_MAP_FILE_NAME)
 	r := csv.NewReader(file)
@@ -88,6 +98,7 @@ func LoadIndexMap(file io.Reader) (map[string]IndexMapEntry, error) {
 	return indexMap, nil
 }
 
+// getIndexMapPath returns the file path to the IndexMap csv file.
 func getIndexMapPath() string {
 	return filepath.Join(appDir.GetBaseDir(), INDEX_MAP_FILE_NAME)
 }

internal/log/logs.go

@@ -1,3 +1,4 @@
+// Package logs provides primitives to initialise and access the logger.
 package logs
 
 import (
@@ -15,6 +16,7 @@ var (
 	ErrorLogger   *log.Logger
 )
 
+// Init initialises the log file and the different loggers: WarningLogger, InfoLogger and ErrorLogger.
 func Init() error {
 	file, err := os.OpenFile(getLogPath(), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0666)
 	if err != nil {
@@ -30,6 +32,7 @@ func Init() error {
 	return nil
 }
 
+// getLogPath returns the file path to the log file.
 func getLogPath() string {
 	return filepath.Join(appDir.GetBaseDir(), lominus.LOG_FILE_NAME)
 }

internal/lominus/lominus.go

@@ -1,3 +1,4 @@
+// Package lominus provides app config constants.
 package lominus
 
 const APP_NAME = "Lominus"

internal/notifications/notifications.go

@@ -1,12 +1,16 @@
+// Package notifications provides primitives to initialise the notification channel.
 package notifications
 
+// Notification struct
 type Notification struct {
 	Title   string
 	Content string
 }
 
 var NotificationChannel chan Notification
 
+// Init initialises the notification channel which can be used to push notifications
+// to the user.
 func Init() {
 	NotificationChannel = make(chan Notification)
 }

internal/ui/systray.go

@@ -1,3 +1,4 @@
+// Package ui provides primitives that initialises the UI.
 package ui
 
 import (
@@ -12,6 +13,7 @@ import (
 
 var lastRanItem *systray.MenuItem
 
+// onReady builds and initialises the system tray UI.
 func onReady() {
 	systray.SetIcon(resourceAppIconIco.Content())
 	systray.SetTitle(lominus.APP_NAME)
@@ -41,6 +43,7 @@ func onReady() {
 	}()
 }
 
+// onExit describes the actions taken when user quits the system tray.
 func onExit() {
 	logs.InfoLogger.Println("lominus quit")
 	mainApp.Quit()

internal/ui/ui.go

@@ -1,3 +1,4 @@
+// Package ui provides primitives that initialises the UI.
 package ui
 
 import (
@@ -49,6 +50,7 @@ var frequencyMap = map[int]string{
 var mainApp fyne.App
 var w fyne.Window
 
+// Init builds and initialises the UI.
 func Init() error {
 	if runtime.GOOS == "windows" {
 		systray.Register(onReady, onExit)
@@ -103,6 +105,7 @@ func Init() error {
 	return nil
 }
 
+// getCredentialsTab builds the credentials tab in the main UI.
 func getCredentialsTab(parentWindow fyne.Window) (*container.TabItem, error) {
 	tab := container.NewTabItem("Login Info", container.NewVBox())
 
@@ -164,6 +167,7 @@ func getCredentialsTab(parentWindow fyne.Window) (*container.TabItem, error) {
 	return tab, nil
 }
 
+// getPreferencesTab builds the preferences tab in the main UI.
 func getPreferencesTab(parentWindow fyne.Window) (*container.TabItem, error) {
 	tab := container.NewTabItem("Preferences", container.NewVBox())
 
@@ -247,6 +251,7 @@ func getPreferencesTab(parentWindow fyne.Window) (*container.TabItem, error) {
 	return tab, nil
 }
 
+// getIntegrationsTab builds the integrations tab in the main UI.
 func getIntegrationsTab(parentWindow fyne.Window) (*container.TabItem, error) {
 	tab := container.NewTabItem("Integrations", container.NewVBox())
 
@@ -310,6 +315,7 @@ func getIntegrationsTab(parentWindow fyne.Window) (*container.TabItem, error) {
 	return tab, nil
 }
 
+// getPreferences is a util function that retrieves the user's preferences.
 func getPreferences() appPref.Preferences {
 	preference, err := pref.LoadPreferences(appPref.GetPreferencesPath())
 	if err != nil {
@@ -319,6 +325,7 @@ func getPreferences() appPref.Preferences {
 	return preference
 }
 
+// getSyncButton builds the sync button in the main UI.
 func getSyncButton(parentWindow fyne.Window) *widget.Button {
 	return widget.NewButton("Sync Now", func() {
 		preferences := getPreferences()
@@ -334,6 +341,7 @@ func getSyncButton(parentWindow fyne.Window) *widget.Button {
 	})
 }
 
+// getQuitButton builds the quit button in the main UI.
 func getQuitButton() *widget.Button {
 	return widget.NewButton("Quit Lominus", func() {
 		if appApp.GetOs() == "windows" {