From: Wolfgang Bumiller <w.bumiller@proxmox.com>
To: Max Carrara <m.carrara@proxmox.com>
Cc: pve-devel@lists.proxmox.com
Subject: Re: [pve-devel] [PATCH v1 pve-storage 0/8] Base Module + Documentation for PVE::Storage::Plugin API
Date: Fri, 11 Apr 2025 15:27:38 +0200 [thread overview]
Message-ID: <tpzhyuwoofx5w5euthtvqby7jvsifbshwwqm7hyxcwdzto5vm4@oamylugkplg7> (raw)
In-Reply-To: <20250326142059.261938-1-m.carrara@proxmox.com>
On Wed, Mar 26, 2025 at 03:20:51PM +0100, Max Carrara wrote:
> 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.
As a high-level comment: In an API with external plugins, I'd prefer to
avoid default values. They may not apply to all storages. While
technically those would now be documented, future additions to the API
which get inherited with default values are still a problem.
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
prev parent reply other threads:[~2025-04-11 13:27 UTC|newest]
Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-03-26 14:20 Max Carrara
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 1/8] pluginbase: introduce PVE::Storage::PluginBase with doc scaffold Max Carrara
2025-03-31 15:13 ` Fabian Grünbichler
2025-04-02 16:31 ` Max Carrara
2025-04-03 7:12 ` Fabian Grünbichler
2025-04-03 14:05 ` Max Carrara
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 2/8] pluginbase: add high-level plugin API description Max Carrara
2025-03-31 15:13 ` Fabian Grünbichler
2025-04-02 16:31 ` Max Carrara
2025-04-03 7:12 ` Fabian Grünbichler
2025-04-03 14:05 ` Max Carrara
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 3/8] pluginbase: document SectionConfig methods Max Carrara
2025-03-31 15:13 ` Fabian Grünbichler
2025-04-02 16:31 ` Max Carrara
2025-04-11 13:49 ` Wolfgang Bumiller
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 4/8] pluginbase: document general plugin methods Max Carrara
2025-03-28 12:50 ` Maximiliano Sandoval
2025-03-31 15:12 ` Fabian Grünbichler
2025-04-02 16:31 ` Max Carrara
2025-04-11 14:04 ` Wolfgang Bumiller
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 5/8] pluginbase: document hooks Max Carrara
2025-03-28 13:07 ` Maximiliano Sandoval
2025-03-31 15:12 ` Fabian Grünbichler
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 6/8] pluginbase: document image operation methods Max Carrara
2025-03-31 15:12 ` Fabian Grünbichler
2025-04-02 16:32 ` Max Carrara
2025-04-03 7:23 ` Fabian Grünbichler
2025-04-03 14:05 ` Max Carrara
2025-04-11 14:08 ` Wolfgang Bumiller
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 7/8] pluginbase: document volume operations Max Carrara
2025-03-31 15:12 ` Fabian Grünbichler
2025-04-02 16:32 ` Max Carrara
2025-04-14 8:24 ` Wolfgang Bumiller
2025-03-26 14:20 ` [pve-devel] [PATCH v1 pve-storage 8/8] pluginbase: document import and export methods Max Carrara
2025-04-01 8:40 ` Fabian Grünbichler
2025-04-01 9:40 ` Fiona Ebner
2025-04-14 14:35 ` Wolfgang Bumiller
2025-04-02 16:32 ` Max Carrara
2025-04-11 13:27 ` Wolfgang Bumiller [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=tpzhyuwoofx5w5euthtvqby7jvsifbshwwqm7hyxcwdzto5vm4@oamylugkplg7 \
--to=w.bumiller@proxmox.com \
--cc=m.carrara@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal