More documentation fixes

armor/armor.go

@@ -1,4 +1,5 @@
-// This package contains a set of helper methods for armoring and unarmoring
+// Package armor contains a set of helper methods for armoring and unarmoring
+// data.
 package armor
 
 import (
@@ -12,17 +13,18 @@ import (
 	"io/ioutil"
 )
 
-// ArmorKey makes bytes input key to armor format
+// ArmorKey armors input as a public key.
 func ArmorKey(input []byte) (string, error) {
 	return ArmorWithType(input, constants.PublicKeyHeader)
 }
 
-// ArmorWithTypeBuffered takes input from io.Writer and returns io.WriteCloser which can be read for armored code
+// ArmorWithTypeBuffered returns a io.WriteCloser which, when written to, writes
+// armored data to w with the given armorType.
 func ArmorWithTypeBuffered(w io.Writer, armorType string) (io.WriteCloser, error) {
 	return armor.Encode(w, armorType, nil)
 }
 
-// ArmorWithType makes bytes input to armor format
+// ArmorWithType armors input with the given armorType.
 func ArmorWithType(input []byte, armorType string) (string, error) {
 	var b bytes.Buffer
 
@@ -39,7 +41,7 @@ func ArmorWithType(input []byte, armorType string) (string, error) {
 	return b.String(), nil
 }
 
-// Unarmor an armored key to bytes key
+// Unarmor unarmors an armored key.
 func Unarmor(input string) ([]byte, error) {
 	b, err := internal.Unarmor(input)
 	if err != nil {
@@ -48,7 +50,7 @@ func Unarmor(input string) ([]byte, error) {
 	return ioutil.ReadAll(b.Body)
 }
 
-// ReadClearSignedMessage reads clear message from a clearsign package (package containing cleartext and signature)
+// ReadClearSignedMessage returns the message body from a clearsigned message.
 func ReadClearSignedMessage(signedMessage string) (string, error) {
 	modulusBlock, rest := clearsign.Decode([]byte(signedMessage))
 	if len(rest) != 0 {

constants/armor.go

@@ -1,6 +1,7 @@
+// Package constants provides a set of common OpenPGP constants.
 package constants
 
-// Definitions for armored data
+// Constants for armored data.
 const (
 	ArmorHeaderVersion = "GopenPGP 0.0.1 (" + Version + ")"
 	ArmorHeaderComment = "https://gopenpgp.org"

constants/cipher.go

@@ -1,9 +1,9 @@
 package constants
 
-// Definitions for cipher suites
+// Cipher suite names.
 const (
 	ThreeDES  = "3des"
-	TripleDES = "tripledes"
+	TripleDES = "tripledes" // Both "3des" and "tripledes" refer to 3DES.
 	CAST5     = "cast5"
 	AES128    = "aes128"
 	AES192    = "aes192"

crypto/keyring.go

@@ -174,7 +174,7 @@ func (kr *KeyRing) Encrypt(w io.Writer, sign *KeyRing, filename string, canonica
 		func() time.Time { return GetGopenPGP().GetTime() })
 }
 
-// EncryptCore is common encryption method for desktop and mobile clients
+// EncryptCore is lower-level encryption method used by KeyRing.Encrypt.
 func EncryptCore(w io.Writer, encryptEntities []*openpgp.Entity, signEntity *openpgp.Entity, filename string,
 	canonicalizeText bool, timeGenerator func() time.Time) (io.WriteCloser, error) {
 

internal/armor.go

@@ -5,7 +5,7 @@ import (
 	"strings"
 )
 
-// Unarmor from string
+// Unarmor unarmors an armored string.
 func Unarmor(input string) (*armor.Block, error) {
 	io := strings.NewReader(input)
 	b, err := armor.Decode(io)

internal/common.go

@@ -1,3 +1,4 @@
+// Package internal contains internal methods and constants.
 package internal
 
 import (
@@ -6,17 +7,18 @@ import (
 	"github.com/ProtonMail/gopenpgp/constants"
 )
 
-// TrimNewlines removes a whitespace in the end of string (don't stop on linebreak)
+// TrimNewlines removes whitespace from the end of each line of the input
+// string.
 func TrimNewlines(input string) string {
 	var re = regexp.MustCompile(`(?m)[ \t]*$`)
 	return re.ReplaceAllString(input, "")
 }
 
 // CreationTimeOffset stores the amount of seconds that a signature may be
-// created in the future, to compensate for clock skew
+// created in the future, to compensate for clock skew.
 const CreationTimeOffset = int64(60 * 60 * 24 * 2)
 
-// ArmorHeaders from gopenpgp
+// ArmorHeaders is a map of default armor headers.
 var ArmorHeaders = map[string]string{
 	"Version": constants.ArmorHeaderVersion,
 	"Comment": constants.ArmorHeaderComment,

models/models.go

@@ -1,20 +1,21 @@
-// Provides high-level public data models used for communication mainly with mobile clients
+// Package models provides structs containing message data.
 package models
 
-// EncryptedSplit when encrypt attachment
+// EncryptedSplit contains a separate session key packet and symmetrically
+// encrypted data packet.
 type EncryptedSplit struct {
 	DataPacket []byte
 	KeyPacket  []byte
 	Algo       string
 }
 
-// EncryptedSigned encrypt_sign_package
+// EncryptedSigned contains an encrypted message and signature.
 type EncryptedSigned struct {
 	Encrypted string
 	Signature string
 }
 
-// DecryptSignedVerify decrypt_sign_verify
+// DecryptSignedVerify contains a decrypted message and verification result.
 type DecryptSignedVerify struct {
 	//clear text
 	Plaintext string

subtle/subtle.go

@@ -1,3 +1,5 @@
+// Package subtle contains subtly insecure methods not recommended for casual
+// use.
 package subtle
 
 import (