[pve-devel] [PATCH v1 pve-storage 0/8] Base Module + Documentation for PVE::Storage::Plugin API
Max Carrara
m.carrara at proxmox.com
Wed Mar 26 15:20:51 CET 2025
Abstract Base Module + Documentation for PVE::Storage::Plugin API - v1
======================================================================
This series adds a base module (interface) for PVE::Storage::Plugin,
named PVE::Storage::PluginBase, which lists all methods that are part of
the Storage Plugin API. Additionally, docstrings for every method are
added in order to provide context for (third-party) developers, as
sometimes a complete roundtrip through our code is otherwise necessary
in order to (really) understand what a method does.
Special thanks go to @Maximilano, who has helped me out a lot with this
series!
Essentially, the base module is similar to PVE::LXC::Plugin [1], with
the exception that docstrings are added.
Instead of documenting every single parameter separately, common /
recurring method parameters are listed and explained at the very top of
the file. The caching mechanism of a few methods is also described in
the top-level documentation.
Any feedback regarding the docs is highly appreciated -- I hope that we
haven't overlooked anything. We tried to keep things concise unless it's
absolutely necessary to add additional context.
Also, most (but not all) of the methods `croak` right now if they're
unimplemented, but I feel like default return values for certain methods
could be returned instead. Then again, ::Plugin already provides those
defaults, so I'm not sure if it matters either way.
References
----------
[1]: https://git.proxmox.com/?p=pve-container.git;a=blob;f=src/PVE/LXC/Setup/Plugin.pm;h=b9d9c2d9d19e086438faeda6cfce8f854dddc7ea;hb=refs/heads/master
Summary of Changes
------------------
Max Carrara (8):
pluginbase: introduce PVE::Storage::PluginBase with doc scaffold
pluginbase: add high-level plugin API description
pluginbase: document SectionConfig methods
pluginbase: document general plugin methods
pluginbase: document hooks
pluginbase: document image operation methods
pluginbase: document volume operations
pluginbase: document import and export methods
src/PVE/Storage/Makefile | 1 +
src/PVE/Storage/Plugin.pm | 2 +-
src/PVE/Storage/PluginBase.pm | 1475 +++++++++++++++++++++++++++++++++
3 files changed, 1477 insertions(+), 1 deletion(-)
create mode 100644 src/PVE/Storage/PluginBase.pm
--
2.39.5
More information about the pve-devel
mailing list