[pve-devel] [PATCH v1 pve-common 08/18] pbsclient: document package and its public functions & methods

[Max Carrara]

On Mon Nov 11, 2024 at 8:14 PM CET, Thomas Lamprecht wrote:
> Am 02.08.24 um 15:26 schrieb Max Carrara:
> > This commit adds a brief overview for the `PVE::PBSClient` package and
> > documents its public functions and methods. Examples are added where
> > deemed appropriate.
>
> great works and thanks for improving the documentation of perl code, but I
> think making this a bit more concise, e.g. shorting some examples or formats
> might give us a better balance and ROI here, to avoid losing the important
> things in the noise, so to say.
>
> E.g. the 5 extra lines setting some $Data::Dumper modules key seem rather
> out of place to me.

Thanks a lot for your feedback! I agree with you here, shortening some
stuff would make things a little bit more readable.

For now I'm going to remove the extra $Data::Dumper lines and shorten
some of the data structure examples; in the latter case, I initially
tried to show multiple possible values in things like returned file
lists, e.g.:

[
  {
      'crypt-mode' => "encrypt",
      filename => "qemu-server.conf.blob",
      size => 428
  },
  {
      'crypt-mode' => "encrypt",
      filename => "drive-scsi0.img.fidx",
      size => 17179869184
  },
  {
      'crypt-mode' => "sign-only",
      filename => "index.json.blob",
      size => 651
  },
  {
      filename => "client.log.blob"
  },
  ...
]

In this case, I'd shorten it to just the following:

[
  {
      'crypt-mode' => "encrypt",
      filename => "qemu-server.conf.blob",
      size => 428
  },
  ...
]

So, examples like that will be a little bit smaller in the next
revision.

Are there any other cases where you'd prefer to shorten things? I
already tried to be as concise / clear as possible my wording, but maybe
I'm overlooking something.