Package: debhelper
Severity: minor
Tags: newcomer
I think the current documentation for extending debhelper leaves a bit
to be wanted.
As an example:
* I think debhelper should better advice its build system feature.
There has been a few examples of people using a dh sequence to remove
the dh_auto_* tools and replace them with their own similar tooling
that is basically a build system. This suggests we are not
advertising the build system extension point enough in our
documentation.
* The current PROGRAMMING documentation is a reference documentation of
the debhelper API (plus some other things). However, being a
separate document means I tend to forget to update it when I add new
functions in Dh_Lib. It might be better to migrate the documentation
to POD documentation and provide standard perldoc documentation for
Dh_Lib to replace that part of PROGRAMMING.
- Doing a similar thing for Buildsystem.pm might be useful for
improving the documentation for build systems. Our current
documentation is basically "It is possible, read the source".
Note that PROGRAMMING still have bits that do not belong in the
perldoc (like the general dh_* interface of how options are supposed
to be interpreted).
I think the documentation part of this is a rather self-contained task
that should be bite-sized for someone interested in starting to work on
debhelper and is looking for something technically simple to start with
to get accustomed to the setup.
Note that for me, a "newcomer" can be an existing experienced debian
contributor (including uploading DD). Please note I expect interested to
have basic perl knowledge (such as basic POD knowledge and coding
conventions - things like knowing that "_foo" functions are
"private"/not a part of the API).
An example of how I think this task could be solved:
* Extract most of the Dh_Lib documentation from PROGRAMMING, convert it
into POD and inject it into the Dh_Lib.pm. Some things to be aware
of:
- I prefer POD and code being interleaved. That is, the POD for
a function in Dh_Lib should be just above the function itself.
- A few functions might be undocumented in PROGRAMMING. Often these
will have a 1-2 line documentation in Dh_Lib.pm, which might be
enough. But if not, please add a TODO for the function in the
patch/MR and I will write the documentation for that function after
merging (or provide it as a part of the review).
* For Buildsystem.pm, convert it to use POD (like Dh_Lib.pm).
* The PROGRAMMING file should reference the new POD documentation
(such as via "perldoc Debian::Debhelper::Dh_Lib").
- There will be a grey area of how much PROGRAMMING should introduce
the Dh_Lib and the Buildsystem module. Make a cut that ensures the
modules can be read standalone reference documentation.
Stretch goals include providing tutorials or a how-to guide (related
#993677). Though it should probably be in a separate file to avoid
mixing documentation types (more than we already do).
