From 2a671dca0002119019c474ac895a206cb9ac5ce4 Mon Sep 17 00:00:00 2001
From: Filippo Valsorda <hi@filippo.io>
Date: Sun, 7 Dec 2025 19:57:00 +0100
Subject: [PATCH] plugin: improve package and method docs

---
 plugin/client.go |  1 -
 plugin/plugin.go | 10 ++++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/plugin/client.go b/plugin/client.go
index 878cfd7..6e19016 100644
--- a/plugin/client.go
+++ b/plugin/client.go
@@ -4,7 +4,6 @@
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
 
-// Package plugin implements the age plugin protocol.
 package plugin
 
 import (
diff --git a/plugin/plugin.go b/plugin/plugin.go
index a3a9fa7..9ec3a45 100644
--- a/plugin/plugin.go
+++ b/plugin/plugin.go
@@ -1,3 +1,10 @@
+// Package plugin implements the age plugin protocol.
+//
+// [Recipient] and [Indentity] are plugin clients, that execute plugin binaries to
+// perform encryption and decryption operations.
+//
+// [Plugin] is a framework for writing age plugins, that exposes an [age.Recipient]
+// and/or [age.Identity] implementation as a plugin binary.
 package plugin
 
 import (
@@ -71,6 +78,7 @@ func (p *Plugin) RegisterFlags(fs *flag.FlagSet) {
 // If the client supports labels, they will be passed through the protocol.
 //
 // It must be called before [Plugin.Main], and can be called at most once.
+// Otherwise, it panics.
 func (p *Plugin) HandleRecipient(f func(data []byte) (age.Recipient, error)) {
 	if p.recipient != nil {
 		panic("HandleRecipient called twice")
@@ -87,6 +95,7 @@ func (p *Plugin) HandleRecipient(f func(data []byte) (age.Recipient, error)) {
 // If the client supports labels, they will be passed through the protocol.
 //
 // It must be called before [Plugin.Main], and can be called at most once.
+// Otherwise, it panics.
 func (p *Plugin) HandleIdentityAsRecipient(f func(data []byte) (age.Recipient, error)) {
 	if p.idAsRecipient != nil {
 		panic("HandleIdentityAsRecipient called twice")
@@ -99,6 +108,7 @@ func (p *Plugin) HandleIdentityAsRecipient(f func(data []byte) (age.Recipient, e
 // payload.
 //
 // It must be called before [Plugin.Main], and can be called at most once.
+// Otherwise, it panics.
 func (p *Plugin) HandleIdentity(f func(data []byte) (age.Identity, error)) {
 	if p.identity != nil {
 		panic("HandleIdentity called twice")