[pve-devel] [PATCH v1 pve-storage 2/8] pluginbase: add high-level plugin API description

[Max Carrara]

Add a short paragraph in DESCRIPTION serving as an introduction as
well as the GENERAL PARAMETERS and CACHING EXPENSIVE OPERATIONS
sections.

These sections are added in order to avoid repeatedly describing the
same parameters as well as to elaborate on / clarify a couple terms,
e.g. what the $cache parameter does or what a volume in our case is.

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

diff --git a/src/PVE/Storage/PluginBase.pm b/src/PVE/Storage/PluginBase.pm
index e56aa72..16977f3 100644
--- a/src/PVE/Storage/PluginBase.pm
+++ b/src/PVE/Storage/PluginBase.pm
@@ -4,6 +4,83 @@ C<PVE::Storage::PluginBase> - Storage Plugin API Interface
 
 =head1 DESCRIPTION
 
+This module documents the public Storage Plugin API of PVE and serves
+as a base for C<L<PVE::Storage::Plugin>>. Plugins must B<always> inherit from
+C<L<PVE::Storage::Plugin>>, as this module is for documentation purposes
+only.
+
+=head2 DEFAULT IMPLEMENTATIONS
+
+C<L<PVE::Storage::Plugin>> implements most of the methods listed in
+L</PLUGIN INTERFACE METHODS> by default. These provided implementations are
+tailored towards file-based storages and can therefore be used as-is in that
+case. Plugins for other kinds of storages will most likely have to adapt each
+method for their individual use cases.
+
+=head2 GENERAL PARAMETERS
+
+The parameter naming throughout the code is kept as consistent as possible.
+Therefore, common reappearing subroutine parameters are listed here for
+convenience:
+
+=over
+
+=item * C<< \%scfg >>
+
+The storage configuration associated with the given C<$storeid>. This is a
+reference to a hash that represents the section associated with C<$storeid> in
+C</etc/pve/storage.cfg>.
+
+=item * C<< $storeid >>
+
+The ID of the storage. This ID is user-provided; the IDs for existing
+storages can be found in the UI via B<< Datacenter > Storage >>.
+
+=item * C<< $volname >>
+
+The name of a volume. The term I<volume> can refer to a disk image, an ISO
+image, a backup, etc. depending on the content type of the volume.
+
+=item * C<< $volid >>
+
+The ID of a volume, which is essentially C<"${storeid}:${volname}">. Less used
+within the plugin API, but nevertheless relevant.
+
+=item * C<< $snapname >> (or C<< $snap >>)
+
+The name of a snapshot associated with the given C<$volname>.
+
+=item * C<< \%cache >>
+
+See L<CACHING EXPENSIVE OPERATIONS>.
+
+=item * C<< $vmid >>
+
+The ID of a guest (so, either of a VM or a container).
+
+=back
+
+=head2 CACHING EXPENSIVE OPERATIONS
+
+Certain methods take a C<\%cache> as parameter, which is used to store the
+results of time-consuming / expensive operations specific to certain plugins.
+The exact lifetime of the cached data is B<unspecified>, since it depends on
+the exact usage of the C<L<PVE::Storage>> API, but can generally be assumed to
+be B<short-lived>.
+
+For example, the C<L<PVE::Storage::LVMPlugin>> uses this cache to store the
+parsed output of the C<lvs> command. Since the number and precise information
+about LVM's logical volumes is unlikely to change within a short time, other
+API methods can then use this data in order to avoid repeatedly calling and
+parsing the output of C<lvs>.
+
+Third-party plugin developers should ensure that the data stored and retrieved
+is specific to their plugin, and not rely on the data that other plugins might
+store in C<\%cache>. Furthermore, the names of keys should be rather unique in
+the sense that they're unlikely to conflict with any future keys that may be
+introduced internally. To illustrate, e.g. C<myplugin_mounts> should be used
+instead of a plain C<mounts> key.
+
 =cut
 
 package PVE::Storage::PluginBase;
-- 
2.39.5