From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id A703B1FF38F for ; Tue, 4 Jun 2024 11:28:53 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id A11F3E587; Tue, 4 Jun 2024 11:29:23 +0200 (CEST) From: Max Carrara To: pve-devel@lists.proxmox.com Date: Tue, 4 Jun 2024 11:28:47 +0200 Message-Id: <20240604092850.126083-1-m.carrara@proxmox.com> X-Mailer: git-send-email 2.39.2 MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.034 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_SCC_BODY_TEXT_LINE -0.01 - Subject: [pve-devel] [PATCH v1 pve-common 0/3] Section Config: Documentation & Code Cleanup X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" 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