From 8974a1c84810d773e015ec6ad7e92e975c579733 Mon Sep 17 00:00:00 2001
From: Thierry Vignaud <thierry.vignaud@gmail.com>
Date: Fri, 14 Feb 2020 15:29:30 +0100
Subject: partially podify fs::*

---
 perl-install/NEWS                      |  1 +
 perl-install/fs/format.pm              | 95 +++++++++++++++++++++++++++++++---
 perl-install/fs/get.pm                 | 22 +++++++-
 perl-install/fs/partitioning_wizard.pm | 28 ++++++++--
 perl-install/fs/type.pm                | 58 +++++++++++++++++++--
 5 files changed, 188 insertions(+), 16 deletions(-)

diff --git a/perl-install/NEWS b/perl-install/NEWS
index 1304240f2..b7ebeb824 100644
--- a/perl-install/NEWS
+++ b/perl-install/NEWS
@@ -1,6 +1,7 @@
 - update list for modules needing firmware
 - recognize new kernel 5.2 - 5.4 drivers
 - diskdrake:
+  o enhanced internal doc
   o make reformating nilfs2 fses to work
   o support adding partitions to Live ISOs on USB sticks (mga#25224)
 - drakfont:
diff --git a/perl-install/fs/format.pm b/perl-install/fs/format.pm
index 1e1175b3e..b75ed54a6 100644
--- a/perl-install/fs/format.pm
+++ b/perl-install/fs/format.pm
@@ -10,6 +10,20 @@ use fs::type;
 use fs::loopback;
 use log;
 
+=head1 SYNOPSYS
+
+B<fs::format> enables to format filesystems.
+
+=head1 Variables
+
+=over
+
+=item %cmds
+
+For each filesystem, list: [ package_name, command_to_use, options_to_use ]
+
+=cut
+
 my %cmds = (
     ext2     => [ 'e2fsprogs', 'mkfs.ext2', '-F' ],
     ext3     => [ 'e2fsprogs', 'mkfs.ext3', '-F' ],
@@ -27,7 +41,14 @@ my %cmds = (
     nilfs2   => [ 'nilfs-utils', 'mkfs.nilfs2', '-f' ],
 );
 
-my %LABELs = ( #- option, length, handled_by_mount
+
+=item %LABELs
+
+For each filesystem, list: [ option, max_length, handled_by_mount ]
+
+=cut
+
+my %LABELs = (
     ext2     => [ '-L', 16, 1 ],
     ext3     => [ '-L', 16, 1 ],
     ext4     => [ '-L', 16, 1 ],
@@ -44,9 +65,17 @@ my %LABELs = ( #- option, length, handled_by_mount
     nilfs2   => [ '-L', 16, 1 ],
 );
 
-my %edit_LABEL = ( # package, command, option
-# If option is defined, run <command> <option> <label> <device>
-# If no option, run <command> <device> <label>
+=item %edit_LABEL
+
+For each filesystem, list: [ package, command, option ]
+
+If option is defined, run <command> <option> <label> <device>
+
+If no option, run <command> <device> <label>
+
+=cut
+
+my %edit_LABEL = ( # 
     ext2     => [ 'e2fsprogs', 'tune2fs', '-L' ],
     ext3     => [ 'e2fsprogs', 'tune2fs', '-L' ],
     ext4     => [ 'e2fsprogs', 'tune2fs', '-L' ],
@@ -63,13 +92,33 @@ my %edit_LABEL = ( # package, command, option
     nilfs2 => [ 'nilfs-utils', 'nilfs-tune', '-L' ],
 );
 
-# Preserve UUID on fs where we couldn't enforce it while formatting
+=item %preserve_UUID
+
+For each filesystem, list: [ option, max_length, handled_by_mount ]
+
+Those are used in order to preserve UUID on fs where we couldn't enforce it while formatting.
+
+=cut
+
 my %preserve_UUID = ( # package, command
     jfs      => [ 'jfsutils', 'jfs_tune', ],
     xfs      => [ 'xfsprogs', 'xfs_admin' ],
     nilfs2   => [ 'nilfs-utils', 'nilfs-tune' ],
 );
- 
+
+
+=back
+
+=head1 Functions
+
+=over
+
+=item package_needed_for_partition_type($part)
+
+Return the package needed for that partition's type.
+
+=cut
+
 sub package_needed_for_partition_type {
     my ($part) = @_;
     my $l = $cmds{$part->{fs_type}} or return;
@@ -100,6 +149,12 @@ sub canEditLabel {
     to_bool($edit_LABEL{$part->{fs_type}});
 }
 
+=item part($all_hds, $part, $wait_message)
+
+Frontend to part_raw()
+
+=cut
+
 sub part {
     my ($all_hds, $part, $wait_message) = @_;
     if (isRAID($part)) {
@@ -116,6 +171,12 @@ sub part {
     undef $part->{toFormat};
 }
 
+=item write_label($part)
+
+Set the label on the filesystem hold in $part.
+
+=cut
+
 sub write_label {
     my ($part) = @_;
 
@@ -150,6 +211,13 @@ sub write_btrfs_uuid {
     die "failed to set UUID to '$UUID' on $dev (status=$status)" if !$status;
 }
 
+=item part_raw($part, $wait_message)
+
+Actually format the $part partition disk. $wait_message is only used when formating ext3/4.
+If not set, ext[3-4] will be formated without any progression bar, like other fses...
+
+=cut
+
 sub part_raw {
     my ($part, $wait_message) = @_;
 
@@ -223,6 +291,12 @@ sub after_formatting {
     set_isFormatted($part, 1);
 }
 
+=item mkfs_ext3($wait_message, @args)
+
+Display a progression bar whike formating ext3/4
+
+=cut
+
 sub mkfs_ext3 {
     my ($wait_message, @args) = @_;
 
@@ -239,6 +313,12 @@ sub mkfs_ext3 {
     return close($F);
 }
 
+=item disable_forced_fsck($dev)
+
+Disable automatic fsck on extX (infinite number of mounts & duration between 2 fsck runs)
+
+=cut
+
 sub disable_forced_fsck {
     my ($dev) = @_;
     run_program::run("tune2fs", "-c0", "-i0", devices::make($dev));
@@ -310,5 +390,8 @@ sub formatMount_all {
     };
 }
 
+=back
+
+=cut
 
 1;
diff --git a/perl-install/fs/get.pm b/perl-install/fs/get.pm
index a46a30b09..00c807738 100644
--- a/perl-install/fs/get.pm
+++ b/perl-install/fs/get.pm
@@ -11,6 +11,17 @@ use fs;
 use common;
 use log;
 
+
+=head1 SYNOPSYS
+
+B<fs::get> 
+
+=head1 Functions
+
+=over
+
+=cut
+
 sub empty_all_hds() {
     { hds => [], lvms => [], raids => [], dmcrypts => [], loopbacks => [], raw_hds => [], nfss => [], smbs => [], davs => [], special => [] };
 }
@@ -51,7 +62,12 @@ sub hds {
     (@{$all_hds->{hds}}, @{$all_hds->{lvms}});
 }
 
-#- get all normal partition.
+=item hds_fstab(@hds)
+
+Get all normal partition.
+
+=cut
+
 sub hds_fstab {
     map { partition_table::get_normal_parts($_) } @_;
 }
@@ -165,4 +181,8 @@ sub mntpoint_prefixed {
     $::prefix . $part->{mntpoint};
 }
 
+=back
+
+=cut
+
 1;
diff --git a/perl-install/fs/partitioning_wizard.pm b/perl-install/fs/partitioning_wizard.pm
index 8a15ec559..d48b46084 100644
--- a/perl-install/fs/partitioning_wizard.pm
+++ b/perl-install/fs/partitioning_wizard.pm
@@ -14,12 +14,26 @@ use partition_table::raw;
 use partition_table::dos;
 use POSIX qw(ceil);
 
-#- unit of $mb is mega bytes, min and max are in sectors, this
-#- function is used to convert back to sectors count the size of
-#- a partition ($mb) given from the interface (on Resize or Create).
-#- modified to take into account a true bounding with min and max.
+
+=head1 SYNOPSYS
+
+B<fs::partitioning_wizard> implements the partitioning wizard.
+
+=head1 Functions
+
+=over
+
+=item from_Mb($mb, $min, $max)
+
+This function is used to convert back to sectors count the size of
+a partition ($mb) given from the interface (on Resize or Create).
+modified to take into account a true bounding with min and max.
+Unit of $mb is mega bytes, min and max are in sectors.
+
+=cut
+
 sub from_Mb {
-    my ($mb, $min, $max) = @_;
+    emy ($mb, $min, $max) = @_;
     $mb <= to_Mb($min) and return $min;
     $mb >= to_Mb($max) and return $max;
     MB($mb);
@@ -636,4 +650,8 @@ sub main {
     1;
 }
 
+=back
+
+=cut
+
 1;
diff --git a/perl-install/fs/type.pm b/perl-install/fs/type.pm
index 697b8c9d9..f4820e90b 100644
--- a/perl-install/fs/type.pm
+++ b/perl-install/fs/type.pm
@@ -6,6 +6,15 @@ use strict;
 use common;
 use devices;
 
+=head1 SYNOPSYS
+
+B<fs::type> enables to perform various tests on filesystem types.
+
+=head1 Functions
+
+=over
+
+=cut
 
 our @ISA = qw(Exporter);
 our @EXPORT = qw(
@@ -289,6 +298,7 @@ sub type_subpart_from_magic {
     $p;
 }
 
+# helpers
 sub defaultFS() { 'ext4' }
 
 sub true_local_fs_types() { qw(btrfs ext3 ext2 ext4 reiserfs xfs jfs) }
@@ -320,16 +330,42 @@ sub isRecovery {
     );
 }
 
+=item isTrueLocalFS($part)
+
+Like isTrueFS(), to make a distinction between ext3/reiserfs/... and NFS
+ => allow /home on NFS
+
+=cut
+
 sub isTrueFS { isTrueLocalFS($_[0]) || $_[0]{fs_type} eq 'nfs' }
+
+=item isTrueFS($part)
+
+Is is a general purpose file system with the right Unix properties
+
+=cut
+
 sub isTrueLocalFS { member($_[0]{fs_type}, true_local_fs_types()) }
 
-sub isOtherAvailableFS { isESP($_[0]) || isFat_or_NTFS($_[0]) || member($_[0]{fs_type}, 'ufs', 'hfs', 'iso9660') } #- other OS that linux can access its filesystem
+=item isOtherAvailableFS($part)
+
+Is it another OS that linux can access its filesystem
+
+=cut
+
+sub isOtherAvailableFS { isESP($_[0]) || isFat_or_NTFS($_[0]) || member($_[0]{fs_type}, 'ufs', 'hfs', 'iso9660') }
 sub isMountableRW { (isTrueFS($_[0]) || isOtherAvailableFS($_[0])) && $_[0]{fs_type} ne 'ntfs' }
 sub cannotBeMountable { 
     my ($part) = @_;
     isRawRAID($part) || isRawLUKS($part) || isRawLVM($part) || isBIOS_GRUB($part);
 }
-# is not a special sg that cannot be mounted/formatted (parts of RAID/LVM, BIOS_GRUB):
+
+=item isFormatable($part)
+
+Is not a special sg that cannot be mounted/formatted (parts of RAID/LVM, BIOS_GRUB). Basically the reverse of cannotBeMountable().
+
+=cut
+
 sub isFormatable {
     my ($part) = @_;
     !cannotBeMountable($part);
@@ -352,7 +388,12 @@ sub isMounted { $_[0]{isMounted} }
 sub isBusy { isMounted($_[0]) || isPartOfRAID($_[0]) || isPartOfLVM($_[0]) || $_[0]{dm_active} || isPartOfLoopback($_[0]) }
 sub isSpecial { isRAID($_[0]) || isLVM($_[0]) || isLoopback($_[0]) || isUBD($_[0]) }
 
-#- not for partitions, but for hds:
+=item is_dmraid($hd)
+
+Check that a disk (not a partition) is in a fake/soft RAID
+
+=cut
+
 sub is_dmraid { $_[0]{bus} =~ /^dmraid_/ }
 
 sub can_be_this_fs_type {
@@ -377,7 +418,12 @@ sub set_isFormatted {
     delete $part->{fs_type_from_magic};
 }
 
-#- do this before modifying $part->{fs_type}
+=item check($fs_type, $_hd, $part)
+
+Called before before modifying $part->{fs_type}
+
+=cut
+
 sub check {
     my ($fs_type, $_hd, $part) = @_;
     $fs_type eq "jfs" && $part->{size} < MB(16) and die N("You cannot use JFS for partitions smaller than 16MB");
@@ -401,4 +447,8 @@ sub carry_root_loopback {
     any { $_->{mntpoint} eq '/' } @{$part->{loopback} || []};
 }
 
+=back
+
+=cut
+
 1;
-- 
cgit v1.2.1