From 00abbf1af58abd82ba00491e6ca46de04424ef3d Mon Sep 17 00:00:00 2001
From: Carlos Vazquez <fwcarlitos@icloud.com>
Date: Wed, 31 Oct 2018 01:42:54 +0000
Subject: [PATCH] Adds basic documentation for internal packages (#43)

* Added basic documentation wireframe for api, commands, and forms.

* Added doc.go
---
 internal/api/doc.go             | 6 ++++++
 internal/api/photos.go          | 1 +
 internal/api/thumbnails.go      | 1 +
 internal/commands/config.go     | 1 +
 internal/commands/convert.go    | 1 +
 internal/commands/doc.go        | 6 ++++++
 internal/commands/export.go     | 1 +
 internal/commands/import.go     | 1 +
 internal/commands/index.go      | 1 +
 internal/commands/migrate.go    | 1 +
 internal/commands/start.go      | 1 +
 internal/commands/thumbnails.go | 1 +
 internal/forms/doc.go           | 6 ++++++
 13 files changed, 28 insertions(+)
 create mode 100644 internal/api/doc.go
 create mode 100644 internal/commands/doc.go
 create mode 100644 internal/forms/doc.go

diff --git a/internal/api/doc.go b/internal/api/doc.go
new file mode 100644
index 000000000..b8f39d32d
--- /dev/null
+++ b/internal/api/doc.go
@@ -0,0 +1,6 @@
+/*
+Package api contains REST request handlers used by the server package.
+
+See https://photoprism.org/ for more information about PhotoPrism.
+*/
+package api
diff --git a/internal/api/photos.go b/internal/api/photos.go
index eb7345a7c..e354fae41 100644
--- a/internal/api/photos.go
+++ b/internal/api/photos.go
@@ -9,6 +9,7 @@ import (
 	"strconv"
 )
 
+// GetPhotos searches the databse for photos based on a form.
 func GetPhotos(router *gin.RouterGroup, conf *photoprism.Config) {
 	router.GET("/photos", func(c *gin.Context) {
 		var form forms.PhotoSearchForm
diff --git a/internal/api/thumbnails.go b/internal/api/thumbnails.go
index abe99e297..7d90d52ef 100644
--- a/internal/api/thumbnails.go
+++ b/internal/api/thumbnails.go
@@ -14,6 +14,7 @@ var photoIconSvg = []byte(`
 <path d="M21 19V5c0-1.1-.9-2-2-2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2zM8.5 13.5l2.5 3.01L14.5 12l4.5 6H5l3.5-4.5z"/>
 </svg>`)
 
+// GetThumbnail searches the database for a thumbnail based on hash, size, and type.
 func GetThumbnail(router *gin.RouterGroup, conf *photoprism.Config) {
 	router.GET("/thumbnails/:type/:size/:hash", func(c *gin.Context) {
 		fileHash := c.Param("hash")
diff --git a/internal/commands/config.go b/internal/commands/config.go
index da8a249a4..aaaa30439 100644
--- a/internal/commands/config.go
+++ b/internal/commands/config.go
@@ -12,6 +12,7 @@ var ConfigCommand = cli.Command{
 	Action: configAction,
 }
 
+// Prints current configuration; called by ConfigCommand
 func configAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/commands/convert.go b/internal/commands/convert.go
index 4a7967c7e..9098da350 100644
--- a/internal/commands/convert.go
+++ b/internal/commands/convert.go
@@ -13,6 +13,7 @@ var ConvertCommand = cli.Command{
 	Action: convertAction,
 }
 
+// Converts images to JPEG; called by ConvertCommand
 func convertAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/commands/doc.go b/internal/commands/doc.go
new file mode 100644
index 000000000..f3d4a6b7b
--- /dev/null
+++ b/internal/commands/doc.go
@@ -0,0 +1,6 @@
+/*
+This package contains commands and flags to be used by the main application.
+
+See https://photoprism.org/ for more information about PhotoPrism.
+*/
+package commands
diff --git a/internal/commands/export.go b/internal/commands/export.go
index 3e06ee3e8..98dc06137 100644
--- a/internal/commands/export.go
+++ b/internal/commands/export.go
@@ -35,6 +35,7 @@ var exportFlags = []cli.Flag{
 	},
 }
 
+// Exports photos as JPEG; called by ExportCommand and uses exportFlags
 func exportAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/commands/import.go b/internal/commands/import.go
index 888bf7082..5a08cc15b 100644
--- a/internal/commands/import.go
+++ b/internal/commands/import.go
@@ -13,6 +13,7 @@ var ImportCommand = cli.Command{
 	Action: importAction,
 }
 
+// Imports photos from path defined in context arg; called by ImportCommand;
 func importAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/commands/index.go b/internal/commands/index.go
index aaf6d5138..d8c6f23f4 100644
--- a/internal/commands/index.go
+++ b/internal/commands/index.go
@@ -13,6 +13,7 @@ var IndexCommand = cli.Command{
 	Action: indexAction,
 }
 
+// Indexes original photos; called by IndexCommand
 func indexAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/commands/migrate.go b/internal/commands/migrate.go
index 3102c19d2..aad8e1fb3 100644
--- a/internal/commands/migrate.go
+++ b/internal/commands/migrate.go
@@ -12,6 +12,7 @@ var MigrateCommand = cli.Command{
 	Action: migrateAction,
 }
 
+// Automatically migrates / initializes database; called by MigrateCommand
 func migrateAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/commands/start.go b/internal/commands/start.go
index 24ceae229..61c9da380 100644
--- a/internal/commands/start.go
+++ b/internal/commands/start.go
@@ -36,6 +36,7 @@ var startFlags = []cli.Flag{
 	},
 }
 
+// Starts web serve using startFlags; called by startCommand
 func startAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/commands/thumbnails.go b/internal/commands/thumbnails.go
index 494723202..36fa61809 100644
--- a/internal/commands/thumbnails.go
+++ b/internal/commands/thumbnails.go
@@ -27,6 +27,7 @@ var ThumbnailsCommand = cli.Command{
 	Action: thumbnailsAction,
 }
 
+// Creates thumbnail; called by ThumbnailsCommand
 func thumbnailsAction(context *cli.Context) error {
 	conf := photoprism.NewConfig(context)
 
diff --git a/internal/forms/doc.go b/internal/forms/doc.go
new file mode 100644
index 000000000..6b6956802
--- /dev/null
+++ b/internal/forms/doc.go
@@ -0,0 +1,6 @@
+/*
+Package forms contains tagged structs for input value validation.
+
+See https://photoprism.org/ for more information about PhotoPrism.
+*/
+package forms