From c440aa2957f481c656694452b0b48838dd0676bd Mon Sep 17 00:00:00 2001
From: Julien Neuhart <j.neuhart@thecodingmachine.com>
Date: Tue, 3 Apr 2018 11:27:04 +0200
Subject: [PATCH] godoc for file package + renaming some of its struct

---
 app/handlers/converter/file/file.go | 40 +++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 10 deletions(-)

diff --git a/app/handlers/converter/file/file.go b/app/handlers/converter/file/file.go
index d2a68ba6..ef8c861a 100644
--- a/app/handlers/converter/file/file.go
+++ b/app/handlers/converter/file/file.go
@@ -1,3 +1,4 @@
+// Package file implements a solution for handling files coming from a request.
 package file
 
 import (
@@ -10,19 +11,27 @@ import (
 	"github.com/satori/go.uuid"
 )
 
+// File represents a file which has been created
+// from a request.
 type File struct {
-	Type FileType
+	Type Type
 	Path string
 }
 
-type FileType uint32
+// Type represents what kind of file we're dealing with.
+type Type uint32
 
 const (
-	PDFType FileType = iota
+	// PDFType represents a... PDF file.
+	PDFType Type = iota
+	// HTMLType represents an... HTML file.
 	HTMLType
+	// OfficeType represents an... Office document.
 	OfficeType
 )
 
+// NewFile creates a file in the considered directory.
+// Returns a *File instance or an error if something bad happened.
 func NewFile(workingDir string, r io.Reader) (*File, error) {
 	f := &File{
 		Path: MakeFilePath(workingDir),
@@ -58,11 +67,14 @@ func NewFile(workingDir string, r io.Reader) (*File, error) {
 	return f, nil
 }
 
+// MakeFilePath is a simple helper which generates a random file name
+// and associates it with the considered directory to make a path.
 func MakeFilePath(workingDir string) string {
 	return fmt.Sprintf("%s%s", workingDir, uuid.NewV4().String())
 }
 
-var filesTypes = map[ghttp.ContentType]FileType{
+// filesTypes associates a content type with its file kind counterpart.
+var filesTypes = map[ghttp.ContentType]Type{
 	ghttp.PDFContentType:         PDFType,
 	ghttp.HTMLContentType:        HTMLType,
 	ghttp.OctetStreamContentType: OfficeType,
@@ -75,7 +87,8 @@ func (e *fileTypeNotFound) Error() string {
 	return "The file type was not found for the given 'Content-Type'"
 }
 
-func findFileType(f *os.File) (FileType, error) {
+// findFileType tries to detect what kind of file is the given file.
+func findFileType(f *os.File) (Type, error) {
 	ct, err := ghttp.SniffContentType(f)
 	if err != nil {
 		return 999, err
@@ -89,15 +102,21 @@ func findFileType(f *os.File) (FileType, error) {
 	return t, nil
 }
 
-type FileExt string
+// Ext represents a file extension.
+type Ext string
 
 const (
-	PDFExt    FileExt = ".pdf"
-	HTMLExt   FileExt = ".html"
-	OfficeExt FileExt = ""
+	// PDFExt represents a... PDF extension.
+	PDFExt Ext = ".pdf"
+	// HTMLExt represents an... HTML extension.
+	HTMLExt Ext = ".html"
+	// OfficeExt is a empty string, as Office documents
+	// have a lot of different extensions (.docx, .doc and so on).
+	OfficeExt Ext = ""
 )
 
-var filesExtensions = map[FileType]FileExt{
+// filesExtensions associates a kind of file with its extension.
+var filesExtensions = map[Type]Ext{
 	PDFType:    PDFExt,
 	HTMLType:   HTMLExt,
 	OfficeType: OfficeExt,
@@ -109,6 +128,7 @@ func (e *fileExtNotFound) Error() string {
 	return "The file extension was not found for the given file type"
 }
 
+// reworkFilePath renames a file in the considered directory and adds its extension.
 func reworkFilePath(workingDir string, f *File) (*File, error) {
 	ext, ok := filesExtensions[f.Type]
 	if !ok {