Dpkg: Document public module

debian/changelog

@@ -21,6 +21,7 @@ dpkg (1.17.17) UNRELEASED; urgency=low
       when parsing the DEB_BUILD_PROFILES environment variable.
       Thanks to Johannes Schauer <j.schauer@email.de>.
     - New Dpkg::Getopt private module.
+    - Document public module Dpkg.
   * Set the DEB_TARGET_* dpkg-architecture variables from architecture.mk.
     Missed in dpkg 1.17.14.
   * Initialize DEB_TARGET_ARCH variable without requiring DEB_HOST_ARCH,

debian/control

@@ -100,6 +100,7 @@ Description: Dpkg perl modules
  in dpkg-dev. They cover a wide range of functionality. Among them
  there are the following public modules:
  .
+  - Dpkg: core variables
   - Dpkg::BuildFlags: set, modify and query compilation build flags
   - Dpkg::BuildOptions: parse and manipulate DEB_BUILD_OPTIONS
   - Dpkg::Changelog: parse Debian changelogs

scripts/Dpkg.pm

@@ -13,6 +13,19 @@
 
 package Dpkg;
 
+=encoding utf8
+
+=head1 NAME
+
+Dpkg - module with core variables
+
+=head1 DESCRIPTION
+
+The Dpkg module provides a set of variables with information concerning
+this system installation.
+
+=cut
+
 use strict;
 use warnings;
 
@@ -22,6 +35,38 @@ use Exporter qw(import);
 our @EXPORT_OK = qw($PROGNAME $PROGVERSION $CONFDIR $ADMINDIR $LIBDIR $DATADIR);
 our @EXPORT = qw($version $progname $admindir $dpkglibdir $pkgdatadir);
 
+=head1 VARIABLES
+
+=over 4
+
+=item $Dpkg::PROGNAME
+
+Contains the name of the current program.
+
+=item $Dpkg::PROGVERSION
+
+Contains the version of the dpkg suite.
+
+=item $Dpkg::CONFDIR
+
+Contains the path to the dpkg system configuration directory.
+
+=item $Dpkg::ADMINDIR
+
+Contains the path to the dpkg database directory.
+
+=item $Dpkg::LIBDIR
+
+Contains the path to the dpkg methods and plugins directory.
+
+=item $Dpkg::DATADIR
+
+Contains the path to the dpkg architecture tables directory.
+
+=back
+
+=cut
+
 our ($PROGNAME) = $0 =~ m{(?:.*/)?([^/]*)};
 
 # The following lines are automatically fixed at install time
@@ -40,4 +85,19 @@ our $dpkglibdir = $LIBDIR;
 our $pkgdatadir = $DATADIR;
 ## use critic
 
+=head1 CHANGES
+
+=head2 Version 1.01
+
+New variables: $PROGNAME, $PROGVERSION, $CONFDIR, $ADMINDIR, $LIBDIR and
+$DATADIR.
+
+Deprecated variables: $version, $admindir, $dpkglibdir and $pkgdatadir.
+
+=head2 Version 1.00
+
+Mark the module as public.
+
+=cut
+
 1;