docs(v2): Improve documentation in signatures for keys

openpgp/packet/public_key.go

@@ -935,16 +935,9 @@ func userIdSignatureHash(id string, pk *PublicKey, h hash.Hash) (err error) {
 	return nil
 }
 
-// directSignatureHash returns a Hash of the message that needs to be signed
+// directSignatureHash returns a Hash of the message that needs to be signed.
 func directKeySignatureHash(pk *PublicKey, h hash.Hash) (err error) {
-	// RFC 4880, section 5.2.4
-	if err := pk.SerializeSignaturePrefix(h); err != nil {
-		return err
-	}
-	if err := pk.serializeWithoutHeaders(h); err != nil {
-		return err
-	}
-	return nil
+	return pk.SerializeForHash(h)
 }
 
 // VerifyUserIdSignature returns nil iff sig is a valid signature, made by this
@@ -960,8 +953,8 @@ func (pk *PublicKey) VerifyUserIdSignature(id string, pub *PublicKey, sig *Signa
 	return pk.VerifySignature(h, sig)
 }
 
-// VerifyUserIdSignature returns nil iff sig is a valid signature, made by this
-// public key
+// VerifyDirectKeySignature returns nil iff sig is a valid signature, made by this
+// public key.
 func (pk *PublicKey) VerifyDirectKeySignature(sig *Signature) (err error) {
 	h, err := sig.PrepareVerify()
 	if err != nil {

openpgp/v2/subkeys.go

@@ -79,6 +79,7 @@ func (s *Subkey) Serialize(w io.Writer, includeSecrets bool) error {
 	return nil
 }
 
+// ReSign resigns the latest valid subkey binding signature with the given config.
 func (s *Subkey) ReSign(config *packet.Config) error {
 	selectedSig, err := s.LatestValidBindingSignature(time.Time{})
 	if err != nil {

openpgp/v2/user.go

@@ -71,6 +71,7 @@ func readUser(e *Entity, packets *packet.Reader, pkt *packet.UserId) error {
 	return nil
 }
 
+// Serialize serializes the user id to the writer.
 func (i *Identity) Serialize(w io.Writer) error {
 	if err := i.UserId.Serialize(w); err != nil {
 		return err
@@ -135,6 +136,7 @@ func (i *Identity) Revoked(selfCertification *packet.Signature, date time.Time)
 	return false
 }
 
+// ReSign resigns the latest valid self-certification with the given config.
 func (i *Identity) ReSign(config *packet.Config) error {
 	selectedSig, err := i.LatestValidSelfCertification(config.Now())
 	if err != nil {