Document ProductOpener Perl modules.

[zigouras]

Is your feature request related to a problem? Please describe.
There is little to no documentation in the code. Perl POD (plain old documentation) can be used to generate a nice document page.

Describe the solution you'd like
Document all ProductOpener/*.pm modules with Perl POD including functions, classes, variables etc.

Describe alternatives you've considered
Moving blindly through the code.

Additional context
Since these Perl modules are the core of the business logic of the project they should be well documented.

Part of

• 📝 Documenting Product Opener (Tracker) #5559

[stephanegigandet]

Agreed, we are lacking a lot in terms of documentation of the code. A lot of it could also certainly be simplified, reorganized etc. Maybe we can start with some of the simpler / most independent modules (and then also see if we could break / reorganize the more complex / big modules).

I could try with the Imports.pm module first. I have never used POD, is there a good example of POD best practices for documenting a module?

[zigouras]

Here is the official doc page for pod
https://perldoc.perl.org/perlpod.html

It lets you write inline markup in your code for headers, function documentation etc. You then run
perldoc myfile.pm
to see a nicely formatted page.

Thanks for following up.

[VaiTon]

Describe alternatives you've considered
Moving blindly through the code.

Love you <3 lol

[CharlesNepote]

I appreciate recommendations from Damian Conway, in Perl Best Practices (2005). We could start with comment templates for functions and methods.

Structured/templated comments are easier to write (you can't forget anything and it's easier to write) and also to read. Here is what he writes about it:
Create comment templates that are suitable for your team. For example, to inter-
nally document a subroutine or method, you might use something like:

############################################
# Usage      : ????
# Purpose    : ????
# Returns    : ????
# Parameters : ????
# Throws     : no exceptions
# Comments   : none
# See Also   : n/a

which might be filled in like so:

############################################
# Usage      : Config::Auto->get_defaults( )
# Purpose    : Defaults for 'new'
# Returns    : A hash of defaults
# Parameters : none
# Throws     : no exceptions
# Comments   : No corresponding attribute,
#            : gathers data from each
#            : attr_def attribute
# See Also   : $self->set_default( )

We could test it on a module to see if it fits well?

[zigouras]

I think Perl POD is a good option for a few reasons:

• Once POD is written then man pages, html pages, latex files, etc. can be generated from POD. Scripts that are shipped with Perl such as pod2html and pod2latex do this for you.
• POD is the required standard for documentation for modules published on CPAN. Any Perl developer will be familiar with the outline of a POD document.
• It will bring an industry standard to the documentation of your project's code base.

[teolemon]

@zigouras I have started automating generation using GitHub Actions to publish the doc to GitHub page.
Currently it's using perldoc, but I'd like to have your input on what to use, especially if I want navigation between the various doc pages.
https://github.com/openfoodfacts/openfoodfacts-server/pull/5568/files#diff-a3dced34b21949749b803567be31b0966a3d875d413a529cf70fd5b1784a5a4b

[alexgarel]

It has been done since a long time (september 2022), see https://openfoodfacts.github.io/openfoodfacts-server/dev/ref-perl-pod/