Write docs!

admin/sync/doc.go

@@ -0,0 +1,2 @@
+// Package sync provides helpers to import the challenge from various locations.
+package sync

admin/sync/exercice_defines.go

@@ -6,17 +6,20 @@ import (
 	"github.com/BurntSushi/toml"
 )
 
+// ExerciceHintParams holds EHint definition infomation.
 type ExerciceHintParams struct {
 	Filename string
 	Cost     int64
 	Title    string
 }
 
+// ExerciceParams contains values parsed from defines.txt.
 type ExerciceParams struct {
 	Gain int64
 	Hints []ExerciceHintParams `toml:"hint"`
 }
 
+// parseExerciceParams reads challenge definitions from defines.txt and extract usefull data to set up the challenge.
 func parseExerciceParams(i Importer, exPath string) (p ExerciceParams, err error) {
 	var defs string
 	defs, err = getFileContent(i, path.Join(exPath, "defines.txt"))

admin/sync/exercice_files.go

@@ -10,6 +10,8 @@ import (
 	"srs.epita.fr/fic-server/libfic"
 )
 
+// SyncExerciceFiles reads the content of files/ directory and import it as EFile for the given challenge.
+// It takes care of DIGESTS.txt and ensure imported files match.
 func SyncExerciceFiles(i Importer, exercice fic.Exercice) (errs []string) {
 	// If no files directory, don't display error
 	if ! i.exists(path.Join(exercice.Path, "files")) {

admin/sync/exercice_hints.go

@@ -15,6 +15,7 @@ import (
 	_ "golang.org/x/crypto/blake2b"
 )
 
+// SyncExerciceHints reads the content of hints/ directories and import it as EHint for the given challenge.
 func SyncExerciceHints(i Importer, exercice fic.Exercice) (errs []string) {
 	params, err := parseExerciceParams(i, exercice.Path)
 	if err != nil {

admin/sync/exercice_keys.go

@@ -9,6 +9,8 @@ import (
 	"srs.epita.fr/fic-server/libfic"
 )
 
+// isFullGraphic detects if some rune are not graphic one.
+// This function is usefull to display warning when importing key ending with \r.
 func isFullGraphic(s string) bool {
 	for _, c := range s {
 		if !unicode.IsGraphic(c) {
@@ -18,6 +20,7 @@ func isFullGraphic(s string) bool {
 	return true
 }
 
+// SyncExerciceKeys reads the content of flags.txt and import them as Key for the given challenge.
 func SyncExerciceKeys(i Importer, exercice fic.Exercice) []string {
 	var errs []string
 
@@ -60,6 +63,7 @@ func SyncExerciceKeys(i Importer, exercice fic.Exercice) []string {
 	return errs
 }
 
+// SyncExerciceMCQ reads the content of flags-ucq.txt and flags-mcq.txt, and import them as MCQs for the given challenge.
 func SyncExerciceMCQ(i Importer, exercice fic.Exercice) (errs []string) {
 	if _, err := exercice.WipeMCQs(); err != nil {
 		errs = append(errs, err.Error())

admin/sync/file.go

@@ -16,10 +16,15 @@ import (
 	"golang.org/x/crypto/blake2b"
 )
 
+// Importer are abstract methods required to import challenges.
 type Importer interface {
+	// Kind returns information about the Importer, for human interrest.
 	Kind() string
+	// exists checks if the given location exists from the Importer point of view.
 	exists(filename string) bool
+	// toURL gets the full path/URL to the given file, the Importer will look internaly (used for debuging purpose).
 	toURL(filename string) string
+	// importFile imports the file at the given URI
 	importFile(URI string, next func(string, string) (interface{}, error)) (interface{}, error)
 	getFile(filename string, writer *bufio.Writer) error
 	listDir(filename string) ([]string, error)
@@ -62,6 +67,7 @@ func getFile(i Importer, URI string, writer *bufio.Writer) error {
 	return errors.New(fmt.Sprintf("%q: no such file or directory", URI))
 }
 
+// getFileContent
 func getFileContent(i Importer, URI string) (string, error) {
 	cnt := bytes.Buffer{}
 
@@ -72,11 +78,16 @@ func getFileContent(i Importer, URI string) (string, error) {
 	}
 }
 
+// getDestinationFilePath generates the destination path, from the URI.
+// This function permits to obfusce to player the original URI.
+// Theoricaly, changing the import method doesn't change destination URI.
 func getDestinationFilePath(URI string) string {
 	hash := blake2b.Sum512([]byte(URI))
 	return path.Join(fic.FilesDir, strings.ToLower(base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(hash[:])), path.Base(URI))
 }
 
+// ImportFile imports the file at the given URI, using helpers of the given Importer.
+// After import, next is called with relative path where the file has been saved and the original URI.
 func ImportFile(i Importer, URI string, next func(string, string) (interface{}, error)) (interface{}, error) {
 	dest := getDestinationFilePath(URI)