Write docs!

libfic/file.go

@@ -14,20 +14,33 @@ import (
 	_ "golang.org/x/crypto/blake2b"
 )
 
+// FilesDir stores the location where files to be served are stored.
 var FilesDir string = "./FILES/"
+
+// OptionalDigest permits to avoid importation failure if no digest are given.
 var OptionalDigest bool = false
+
+// StrongDigest forces the use of BLAKE2b hash in place of SHA1 (or mixed SHA1/BLAKE2b).
 var StrongDigest bool = false
 
+// EFile represents a challenge file.
 type EFile struct {
 	Id         int64 `json:"id"`
+	// origin holds the import relative path of the file
 	origin     string
+	// Path is the location where the file is stored, relatively to FilesDir
 	Path       string `json:"path"`
+	// IdExercice is the identifier of the underlying challenge
 	IdExercice int64  `json:"idExercice"`
+	// Name is the title displayed to players
 	Name       string `json:"name"`
+	// Checksum stores the cached hash of the file
 	Checksum   []byte `json:"checksum"`
+	// Size contains the cached size of the file
 	Size       int64  `json:"size"`
 }
 
+// GetFiles returns a list of all files living in the database.
 func GetFiles() ([]EFile, error) {
 	if rows, err := DBQuery("SELECT id_file, id_exercice, origin, path, name, cksum, size FROM exercice_files"); err != nil {
 		return nil, err
@@ -50,11 +63,13 @@ func GetFiles() ([]EFile, error) {
 	}
 }
 
+// GetFile retrieves the file with the given id.
 func GetFile(id int) (f EFile, err error) {
 	err = DBQueryRow("SELECT id_file, origin, path, name, cksum, size FROM exercice_files WHERE id_file = ?", id).Scan(&f.Id, &f.origin, &f.Path, &f.Name, &f.Checksum, &f.Size)
 	return f, err
 }
 
+// GetFileByPath retrieves the file that should be found at the given location.
 func GetFileByPath(path string) (EFile, error) {
 	path = strings.TrimPrefix(path, FilesDir)
 
@@ -66,6 +81,7 @@ func GetFileByPath(path string) (EFile, error) {
 	return f, nil
 }
 
+// GetFiles returns a list of files coming with the challenge.
 func (e Exercice) GetFiles() ([]EFile, error) {
 	if rows, err := DBQuery("SELECT id_file, origin, path, name, cksum, size FROM exercice_files WHERE id_exercice = ?", e.Id); err != nil {
 		return nil, err
@@ -89,6 +105,7 @@ func (e Exercice) GetFiles() ([]EFile, error) {
 	}
 }
 
+// GetFileByPath retrieves the file that should be found at the given location, limited to the challenge files.
 func (e Exercice) GetFileByPath(path string) (EFile, error) {
 	path = strings.TrimPrefix(path, FilesDir)
 
@@ -100,6 +117,8 @@ func (e Exercice) GetFileByPath(path string) (EFile, error) {
 	return f, nil
 }
 
+// checkFileHash checks if the file at the given filePath has the given digest.
+// It also returns the file's size.
 func checkFileHash(filePath string, digest []byte) ([]byte, int64, error) {
 	if digest == nil {
 		return []byte{}, 0, errors.New("No digest given.")
@@ -145,6 +164,7 @@ func checkFileHash(filePath string, digest []byte) ([]byte, int64, error) {
 	}
 }
 
+// ImportFile registers (ou updates if it already exists in database) the file in database.
 func (e Exercice) ImportFile(filePath string, origin string, digest []byte) (interface{}, error) {
 	if result512, size, err := checkFileHash(filePath, digest); !OptionalDigest && err != nil {
 		return EFile{}, err
@@ -169,6 +189,7 @@ func (e Exercice) ImportFile(filePath string, origin string, digest []byte) (int
 	}
 }
 
+// AddFile creates and fills a new struct File and registers it into the database.
 func (e Exercice) AddFile(path string, origin string, name string, checksum []byte, size int64) (EFile, error) {
 	if res, err := DBExec("INSERT INTO exercice_files (id_exercice, origin, path, name, cksum, size) VALUES (?, ?, ?, ?, ?, ?)", e.Id, origin, path, name, checksum, size); err != nil {
 		return EFile{}, err
@@ -179,6 +200,7 @@ func (e Exercice) AddFile(path string, origin string, name string, checksum []by
 	}
 }
 
+// Update applies modifications back to the database.
 func (f EFile) Update() (int64, error) {
 	if res, err := DBExec("UPDATE exercice_files SET id_exercice = ?, origin = ?, path = ?, name = ?, cksum = ?, size = ? WHERE id_file = ?", f.IdExercice, f.origin, f.Path, f.Name, f.Checksum, f.Size, f.Id); err != nil {
 		return 0, err
@@ -189,6 +211,7 @@ func (f EFile) Update() (int64, error) {
 	}
 }
 
+// Delete the file from the database.
 func (f EFile) Delete() (int64, error) {
 	if res, err := DBExec("DELETE FROM exercice_files WHERE id_file = ?", f.Id); err != nil {
 		return 0, err
@@ -199,6 +222,7 @@ func (f EFile) Delete() (int64, error) {
 	}
 }
 
+// WipeFiles deletes (only in the database, not on disk) files coming with the challenge.
 func (e Exercice) WipeFiles() (int64, error) {
 	if res, err := DBExec("DELETE FROM exercice_files WHERE id_exercice = ?", e.Id); err != nil {
 		return 0, err
@@ -209,6 +233,7 @@ func (e Exercice) WipeFiles() (int64, error) {
 	}
 }
 
+// ClearFiles removes all certificates from database (but not files on disks).
 func ClearFiles() (int64, error) {
 	if res, err := DBExec("DELETE FROM exercice_files"); err != nil {
 		return 0, err
@@ -219,6 +244,7 @@ func ClearFiles() (int64, error) {
 	}
 }
 
+// GetOrigin access the private field origin of the file.
 func (f EFile) GetOrigin() string {
 	return f.origin
 }