Add documentation to all main packages

aes/decryptor.go

@@ -1,3 +1,6 @@
+/*
+Package aes defines a Cipher that uses 256-bit AES-GCM authenticated encryption to encrypt values the SOPS tree.
+*/
 package aes //import "go.mozilla.org/sops/aes"
 
 import (

config/config.go

@@ -1,3 +1,6 @@
+/*
+Package config provides a way to find and load SOPS configuration files
+*/
 package config //import "go.mozilla.org/sops/config"
 
 import (

decrypt/decrypt.go

@@ -1,3 +1,7 @@
+/*
+Package decrypt is the external API other Go programs can use to decrypt SOPS files. It is the only package in SOPS with
+a stable API.
+*/
 package decrypt // import "go.mozilla.org/sops/decrypt"
 
 import (

keyservice/keyservice.go

@@ -1,3 +1,7 @@
+/*
+Package keyservice implements a gRPC API that can be used by SOPS to encrypt and decrypt the data key using remote
+master keys.
+*/
 package keyservice
 
 import (

kms/keysource.go

@@ -1,3 +1,7 @@
+/*
+Package kms contains an implementation of the go.mozilla.org/sops.MasterKey interface that encrypts and decrypts the
+data key using AWS KMS with the AWS Go SDK.
+*/
 package kms //import "go.mozilla.org/sops/kms"
 
 import (

pgp/keysource.go

@@ -1,3 +1,7 @@
+/*
+Package pgp contains an implementation of the go.mozilla.org/sops.MasterKey interface that encrypts and decrypts the
+data key by first trying with the golang.org/x/crypto/openpgp package and if that fails, by calling the "gpg" binary.
+ */
 package pgp //import "go.mozilla.org/sops/pgp"
 
 import (

stores/stores.go

@@ -1,3 +1,12 @@
+/*
+Package stores acts as a layer between the internal representation of encrypted files and the encrypted files
+themselves.
+
+Subpackages implement serialization and deserialization to multiple formats.
+
+This package defines the structure SOPS files should have and conversions to and from the internal representation. Part
+of the purpose of this package is to make it easy to change the SOPS file format while remaining backwards-compatible.
+*/
 package stores
 
 import (
@@ -10,10 +19,9 @@ import (
 	"go.mozilla.org/sops/pgp"
 )
 
-// SopsFile is a struct used by the stores as a helper unmarshal the SOPS metadata
+// SopsFile is a struct used by the stores as a helper to unmarshal the SOPS metadata
 type SopsFile struct {
-	Data     interface{} `yaml:"data" json:"data"`
-	Metadata Metadata    `yaml:"sops" json:"sops"`
+	Metadata Metadata `yaml:"sops" json:"sops"`
 }
 
 // Metadata is stored in SOPS encrypted files, and it contains the information necessary to decrypt the file.