[pve-devel] [PATCH pve-common v1 19/23] sectionconfig: extend / correct docstring of `private()` method

[Max R. Carrara]

At the end of the docstring, note that ..

* one really should only declare default properties as required in
  very special cases, such as using a property as an identifier

* and that only attributes specific to PVE::JSONSchema should be
  declared on default properties

The latter case in particular was mentioned off-list a while ago;
every default property must be defined through a valid JSONSchema, any
other attributes really shouldn't be added.

Also correct the example in this docstring along the way, correctly
quoting the key and adding `optional => 1` in order not to suggest
anything that is advised against in the new paragraph further below.

Signed-off-by: Max R. Carrara <m.carrara at proxmox.com>
---
 src/PVE/SectionConfig.pm | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/PVE/SectionConfig.pm b/src/PVE/SectionConfig.pm
index 6ad8772..71a0019 100644
--- a/src/PVE/SectionConfig.pm
+++ b/src/PVE/SectionConfig.pm
@@ -138,9 +138,10 @@ More precisely, this method returns a hash with the following structure:
                 optional => 1,
                 description => 'example property',
             },
-            some-property => {
-                description => 'another example property',
+            'some-property' => {
                 type => 'boolean'
+                optional => 1,
+                description => 'another example property',
             },
         },
         options => {
@@ -204,6 +205,19 @@ plugin architecture upfront, for example:
 Additional properties defined in I<child plugins> are stored in the
 C<propertyList> key. See C<L<< properties()|/$plugin->properties() >>>.
 
+B<NOTE:> It is advised to mark all default properties in C<propertyList> as
+optional using C<< optional => 1 >>, with only very few exceptions. One such
+exception would be a property that you intend to use as unique identifier of a
+section. In that case, ensure that you explicitly define it with
+C<< optional => 0 >> and that it is not used in any child plugins'
+C<L<< options()|/$plugin->options() >>> method.
+
+B<NOTE:> When specifying the default properties in the C<propertyList> key, you
+MAY only add attributes related to C<L<PVE::JSONSchema>> to property
+definitions. Any other attributes, even those specific to C<PVE::SectionConfig>
+(like C<fixed>), are not considered valid. All properties in C<propertyList>
+MUST be defined through a valid JSONSchema.
+
 =cut
 
 sub private {
-- 
2.47.3