[pve-devel] [PATCH v1 pve-storage 0/8] Base Module + Documentation for PVE::Storage::Plugin API

[Max Carrara <m.carrara@proxmox.com>]

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



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel