From e4defbcb6d209fa6c8e0d74c54b0ba4406be27df Mon Sep 17 00:00:00 2001
From: Derek McGowan <derek@mcgstyle.net>
Date: Thu, 5 Oct 2017 17:03:38 -0700
Subject: [PATCH] Add documentation for metadata database

Add documentation and explanation for migrations.

Signed-off-by: Derek McGowan <derek@mcgstyle.net>
---
 metadata/db.go         | 22 ++++++++++++++++++++++
 metadata/migrations.go | 10 ++++++++++
 2 files changed, 32 insertions(+)

diff --git a/metadata/db.go b/metadata/db.go
index 08a0dbd04..aed6f1e9a 100644
--- a/metadata/db.go
+++ b/metadata/db.go
@@ -27,12 +27,19 @@ const (
 	dbVersion = 1
 )
 
+// DB represents a metadata database backed by a bolt
+// database. The database is fully namespaced and stores
+// image, container, namespace, snapshot, and content data
+// while proxying data shared across namespaces to backend
+// datastores for content and snapshots.
 type DB struct {
 	db *bolt.DB
 	ss map[string]snapshot.Snapshotter
 	cs content.Store
 }
 
+// NewDB creates a new metadata database using the provided
+// bolt database, content store, and snapshotters.
 func NewDB(db *bolt.DB, cs content.Store, ss map[string]snapshot.Snapshotter) *DB {
 	return &DB{
 		db: db,
@@ -41,6 +48,8 @@ func NewDB(db *bolt.DB, cs content.Store, ss map[string]snapshot.Snapshotter) *D
 	}
 }
 
+// Init ensures the database is at the correct version
+// and performs any needed migrations.
 func (m *DB) Init(ctx context.Context) error {
 	// errSkip is used when no migration or version needs to be written
 	// to the database and the transaction can be immediately rolled
@@ -54,7 +63,14 @@ func (m *DB) Init(ctx context.Context) error {
 			version = 0
 		)
 
+		// i represents the index of the first migration
+		// which must be run to get the database up to date.
+		// The migration's version will be checked in reverse
+		// order, decrementing i for each migration which
+		// represents a version newer than the current
+		// database version
 		i := len(migrations)
+
 		for ; i > 0; i-- {
 			migration := migrations[i-1]
 
@@ -116,6 +132,8 @@ func (m *DB) Init(ctx context.Context) error {
 	return err
 }
 
+// ContentStore returns a namespaced content store
+// proxied to a content store.
 func (m *DB) ContentStore() content.Store {
 	if m.cs == nil {
 		return nil
@@ -123,6 +141,8 @@ func (m *DB) ContentStore() content.Store {
 	return newContentStore(m, m.cs)
 }
 
+// Snapshotter returns a namespaced content store for
+// the requested snapshotter name proxied to a snapshotter.
 func (m *DB) Snapshotter(name string) snapshot.Snapshotter {
 	sn, ok := m.ss[name]
 	if !ok {
@@ -131,10 +151,12 @@ func (m *DB) Snapshotter(name string) snapshot.Snapshotter {
 	return newSnapshotter(m, name, sn)
 }
 
+// View runs a readonly transaction on the metadata store.
 func (m *DB) View(fn func(*bolt.Tx) error) error {
 	return m.db.View(fn)
 }
 
+// Update runs a writable transation on the metadata store.
 func (m *DB) Update(fn func(*bolt.Tx) error) error {
 	return m.db.Update(fn)
 }
diff --git a/metadata/migrations.go b/metadata/migrations.go
index bc1761f01..997aee298 100644
--- a/metadata/migrations.go
+++ b/metadata/migrations.go
@@ -8,6 +8,16 @@ type migration struct {
 	migrate func(*bolt.Tx) error
 }
 
+// migrations stores the list of database migrations
+// for each update to the database schema. The migrations
+// array MUST be ordered by version from least to greatest.
+// The last entry in the array should correspond to the
+// schemaVersion and dbVersion constants.
+// A migration test MUST be added for each migration in
+// the array.
+// The migrate function can safely assume the version
+// of the data it is migrating from is the previous version
+// of the database.
 var migrations = []migration{
 	{
 		schema:  "v1",