program: Improve comments on account types

program/src/state/buffer.rs

@@ -11,6 +11,19 @@ use super::{Account, AccountDiscriminator, ZeroableOption, SEED_LEN};
 /// Buffer account header.
 ///
 /// A buffer holds a variable amount of data after its header information.
+///
+/// There are two types of buffers: PDA buffer accounts and keypair buffer
+/// accounts. PDA buffer account addresses are derived from a seed and program;
+/// non-canonical buffers also include an authority in the derivation. They can
+/// be converted to metadata accounts via the `initialize` instruction. While it
+/// is possible to change the authority of a PDA buffer account, only the program
+/// upgrade authority can initialize a canonical PDA buffer account into a metadata
+/// account; similarly, for non-canonical PDA buffer accounts, only the authority
+/// used in the derivation can initialize the buffer into a metadata account.
+///
+/// Keypair buffer accounts do not follow a specific derivation and thus cannot
+/// be converted to metadata accounts. They can be used as temporary buffers
+/// for instructions that require data to be passed via accounts.
 //
 // Note: `Buffer` may be loaded directly from account data after only a
 // length check (no owner check). All fields must be valid for any bit

program/src/state/data.rs

@@ -4,15 +4,15 @@ use pinocchio::{error::ProgramError, Address};
 
 use super::{DataSource, ZeroableOption};
 
-/// Metadata account data.
+/// Represents the variable data associated with a metadata account.
 pub enum Data<'a> {
-    /// Represents the case where the metadata is stored on the account.
+    /// Data is stored directly on the account.
     Direct(DirectData<'a>),
 
-    /// Represents the case where the metadata is a URL.
+    /// Data is stored externally and accessed via a URL.
     Url(UrlData<'a>),
 
-    /// Represents the case where the metadata is external data.
+    /// Data is stored in an external account.
     External(&'a ExternalData),
 }
 

program/src/state/header.rs

@@ -12,6 +12,14 @@ use super::{
 };
 
 /// Metadata account header.
+///
+/// A metadata account holds a variable amount of data after its header information.
+///
+/// A metadata account address is a PDA derived from a seed and program;
+/// non-canonical metadata accounts also include an authority in the derivation.
+/// Once a metadata account is initialized, it is not possible to change its seed
+/// and program values; however, it is possible to change its authority (in the
+/// case of a canonical metadata account) and mutable flag.
 //
 // Note: `Header` may be loaded directly from account data after only a
 // length check (no owner check). All fields must be valid for any bit