[pve-devel] [PATCH v1 pve-common 0/3] Section Config: Documentation & Code Cleanup

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

Section Config: Documentation & Code Cleanup
============================================

The main focus of this series is the comprehensive documentation which
is added in patch 01. While not every single quirk and implementation
detail may be covered, it should be decent enough to help developers
quickly get started with writing their own Section Config plugin
architecture.

The docs are written in POD - not necessarily because it is a convenient
format to write documentation in, but rather because the entire Perl
ecosystem uses it. No need to reinvent the wheel. Furthermore, POD is
supported by LSPs (at least Perl Navigator), which means that the
"docstrings" for Section Config methods will actually show up as inlay
hints.

Patch 02 updates the module's code style to be more in line with our
Perl Style Guide [0].

Patch 03 cleans up the Section Config parser's internal logic and makes
its control flow easier to follow. Note that this patch does *not* mean
to change the parsing behaviour in any way, as that would risk
accidentally breaking existing Section Config plugin architectures or
config APIs.

Testing
-------

Even though the existing unit tests pass, it would be nice if someone
could give this series a spin and tried to change or add various config
settings, e.g. storage settings and SDN settings, to make sure that the
updated parser logic really does behave the same as before.

Generating Docs
---------------

If you prefer to read the added docs in a different format, you may use
`perldoc` to render e.g. a webpage of the module's docs instead:

  $ perldoc -ohtml src/PVE/SectionConfig.pm > docs.html
  $ firefox docs.html

Summary of Changes
------------------

Max Carrara (3):
  section config: document package and its methods with POD
  section config: update code style
  section config: clean up parser logic

 src/PVE/SectionConfig.pm | 982 +++++++++++++++++++++++++++++++--------
 1 file changed, 798 insertions(+), 184 deletions(-)

-- 
2.39.2



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