[pve-devel] [PATCH v1 pve-storage 5/8] pluginbase: document hooks

[Max Carrara]

Add docstrings for the following methods:
- on_add_hook
- on_update_hook
- on_delete_hook

Signed-off-by: Max Carrara <m.carrara at proxmox.com>
---
 src/PVE/Storage/PluginBase.pm | 85 ++++++++++++++++++++++++++++++-----
 1 file changed, 74 insertions(+), 11 deletions(-)

diff --git a/src/PVE/Storage/PluginBase.pm b/src/PVE/Storage/PluginBase.pm
index 8a61dc3..b3ce684 100644
--- a/src/PVE/Storage/PluginBase.pm
+++ b/src/PVE/Storage/PluginBase.pm
@@ -626,29 +626,92 @@ sub find_free_diskname {
 
 =head2 HOOKS
 
+The following methods are called whenever a storage associated with the given
+plugin is added, updated, or deleted. These methods are useful for:
+
+=over
+
+=item * Setting up certain prerequisites when adding the storage (and then
+tearing them down again when the storage is deleted)
+
+=item * Handling sensitive parameters that shouldn't be written directly
+to C</etc/pve/storage.cfg> and ought to be stored elsewhere
+
+=item * Ensuring that certain conditions in the configuration are being upheld
+that cannot be done via the remaining API otherwise
+
+=back
+
+and more.
+
+=cut
+
+=head3 $plugin->on_add_hook($storeid, \%scfg, %param)
+
+=head3 $plugin->on_add_hook(...)
+
+B<OPTIONAL:> May be implemented in a storage plugin.
+
+Called during the addition of a storage, before the new storage configuration
+gets written.
+
+C<%param> contains additional key-value arguments, usually sensitive keys that
+have been extracted from C<\%scfg> in order not to write them to the storage
+configuration.
+
+C<die>s in order to abort the addition if there are (grave) problems.
+
+C</etc/pve/storage.cfg> is B<locked> when this method is called.
+
 =cut
 
-# called during addition of storage (before the new storage config got written)
-# die to abort addition if there are (grave) problems
-# NOTE: runs in a storage config *locked* context
 sub on_add_hook {
     my ($class, $storeid, $scfg, %param) = @_;
     return undef;
 }
 
-# called during storage configuration update (before the updated storage config got written)
-# die to abort the update if there are (grave) problems
-# NOTE: runs in a storage config *locked* context
+=head3 $plugin->on_update_hook($storeid, \%scfg, %param)
+
+=head3 $plugin->on_update_hook(...)
+
+B<OPTIONAL:> May be implemented in a storage plugin.
+
+Called during the update of a storage configuration, before the new
+configuration gets written.
+
+C<%param> contains additional key-value arguments, usually sensitive keys that
+have been extracted from C<\%scfg> in order not to write them to the storage
+configuration.
+
+C<die>s in order to abort the config update if there are (grave) problems.
+
+C</etc/pve/storage.cfg> is B<locked> when this method is called.
+
+=cut
+
 sub on_update_hook {
     my ($class, $storeid, $scfg, %param) = @_;
     return undef;
 }
 
-# called during deletion of storage (before the new storage config got written)
-# and if the activate check on addition fails, to cleanup all storage traces
-# which on_add_hook may have created.
-# die to abort deletion if there are (very grave) problems
-# NOTE: runs in a storage config *locked* context
+=head3 $plugin->on_delete_hook($storeid, \%scfg)
+
+=head3 $plugin->on_delete_hook(...)
+
+B<OPTIONAL:> May be implemented in a storage plugin.
+
+Called during the deletion of a storage, before the new storage configuration
+gets written. Also gets called if the activation check during storage
+addition fails in order to clean up all traces which
+C<L<< on_add_hook()|/"$plugin->on_add_hook($storeid, \%scfg, %param)" >>>
+may have created.
+
+C<die>s in order to abort the deletion of there are (very grave) problems.
+
+C</etc/pve/storage.cfg> is B<locked> when this method is called.
+
+=cut
+
 sub on_delete_hook {
     my ($class, $storeid, $scfg) = @_;
     return undef;
-- 
2.39.5