enhance partition_table doc

3 files changed, 83 insertions, 7 deletions

diff --git a/perl-install/partition_table.pm b/perl-install/partition_table.pm
index 791e8254b..da53822d1 100644
--- a/perl-install/partition_table.pm
+++ b/perl-install/partition_table.pm
@@ -289,6 +289,12 @@ sub initialize {
     will_tell_kernel($hd, 'init');
 }
 
+=item read_primary($hd)
+
+Identify the partition table type of $hd and return a blessed $pt of type partition_table::TYPE.
+
+=cut
+
 sub read_primary {
     my ($hd) = @_;
 
@@ -351,6 +357,14 @@ sub read {
     1;
 }
 
+=item read_extended($hd, $extended, $need_removing_empty_extended)
+
+Actually load the partition list from the blessed $pt of type partition_table::TYPE.
+
+It uses partition_table::TYPE::read_one()
+
+=cut
+
 sub read_extended {
     my ($hd, $extended, $need_removing_empty_extended) = @_;
 
@@ -391,6 +405,12 @@ sub read_extended {
     }
 }
 
+=item will_tell_kernel($hd, $action, $o_part, $o_delay)
+
+Rembmer the actions to perform on the partition table that the kernel will later be made aware of.
+
+=cut
+
 sub will_tell_kernel {
     my ($hd, $action, $o_part, $o_delay) = @_;
 
@@ -430,6 +450,18 @@ sub will_tell_kernel_delayed {
     }
 }
 
+=item tell_kernel($hd, $tell_kernel)
+
+Tell the kernel that the partition layout has changed.
+
+Take a list of [$action, $part_number, $o_start, $o_size].
+Action can be either 'add' or 'del'.
+Size is not needed when deleting a partition.
+
+eg: ['add', '3', '5000', '1000']
+
+=cut
+
 sub tell_kernel {
     my ($hd, $tell_kernel) = @_;
 
diff --git a/perl-install/partition_table/dos.pm b/perl-install/partition_table/dos.pm
index 92b28beee..51c82e108 100644
--- a/perl-install/partition_table/dos.pm
+++ b/perl-install/partition_table/dos.pm
@@ -14,6 +14,16 @@ use fs::proc_partitions;
 use fs::type;
 use c;
 
+=head1 SYNOPSYS
+
+Read/write MBR partition tables
+
+=head1 Functions
+
+=over
+
+=cut
+
 my @fields = qw(active start_head start_sec start_cyl pt_type end_head end_sec end_cyl start size);
 my $format = "C8 V2";
 my $magic = "\x55\xAA";
@@ -95,7 +105,12 @@ sub CHS2rawCHS {
     [ $c & 0xff, $h, ($s + 1) | (($c >> 2) & 0xc0) ];
 }
 
-# returns (cylinder, head, sector)
+=item sector2CHS($geom, $start)
+
+returns (cylinder, head, sector)
+
+=cut
+
 sub sector2CHS {
     my ($geom, $start) = @_;
     my ($s, $h);
@@ -239,7 +254,12 @@ sub read_one {
     [ @pt ];
 }
 
-# prepare to write the partition table (and extended ones)
+=item start_write($hd)
+
+Prepare to write the partition table (and extended ones)
+
+=cut
+
 sub start_write {
     my ($hd) = @_;
 
@@ -256,8 +276,13 @@ sub start_write {
     $F;
 }
 
-# write the partition table (and extended ones)
-# for each entry, it uses fields: start, size, pt_type, active
+=item start_write($hd, $F, $sector, $pt)
+
+Write the partition table (and extended ones).
+For each entry, it uses fields: start, size, pt_type, active
+
+=cut
+
 sub write {
     my ($hd, $F, $sector, $pt) = @_;
 
diff --git a/perl-install/partition_table/gpt.pm b/perl-install/partition_table/gpt.pm
index 010bac6fe..c155ed48e 100644
--- a/perl-install/partition_table/gpt.pm
+++ b/perl-install/partition_table/gpt.pm
@@ -10,9 +10,19 @@ use fs::type;
 use partition_table::raw;
 use c;
 
+=head1 SYNOPSYS
+
+Read/write GUID partition tables (GPT)
+
+See https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs for a list of exitings GUIDs
+
+=head1 Functions
+
+=over
+
+=cut
 my $nb_primary = 128;
 
-# See https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs for a list of exitings GUIDs
 
 sub first_usable_sector { 34 }
 
@@ -119,8 +129,13 @@ sub write {
     $commit_level;
 }
 
-# Hint partition_table::write() that telling the kernel to reread the
-# partition_table is not needed if we already succeeded in that:
+=item need_to_tell_kernel($hd)
+
+Hint partition_table::write() that telling the kernel to reread the
+partition_table is not needed if we already succeeded in that
+
+=cut
+
 sub need_to_tell_kernel {
     my ($hd) = @_;
     # If we failed, try again (partion_table::tell_kernel() will unmount some partitions first)
@@ -139,4 +154,8 @@ sub can_add { &can_raw_add }
 sub adjustStart {}
 sub adjustEnd {}
 
+=back
+
+=cut
+
 1;