From ac656a1c73103b06962ab6199da16a8607528c19 Mon Sep 17 00:00:00 2001
From: "Thierry.Vignaud" <thierry.vignaud@gmail.com>
Date: Wed, 28 May 2014 22:37:23 +0200
Subject: document stage2 entry point

---
 perl-install/install/install2.pm | 141 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 130 insertions(+), 11 deletions(-)

diff --git a/perl-install/install/install2.pm b/perl-install/install/install2.pm
index 3beb8692c..fb1fd3aa8 100644
--- a/perl-install/install/install2.pm
+++ b/perl-install/install/install2.pm
@@ -6,6 +6,12 @@ use vars qw($o);
 
 BEGIN { $::isInstall = 1 }
 
+=head1 SYNOPSYS
+
+The installer stage2 real entry point
+
+=cut
+
 #-######################################################################################
 #- misc imports
 #-######################################################################################
@@ -30,10 +36,26 @@ use fs::mount;
 use messages;
 
 #-#######################################################################################
-#-$O
-#-the big struct which contain, well everything (globals + the interactive methods ...)
-#-if you want to do a kickstart file, you just have to add all the required fields (see for example
-#-the variable $default)
+=head1 Data Structure
+
+=head2 $O;
+
+$o (or $::o in other modules) is the big struct which contain, well everything:
+
+=over 4
+
+=item * globals
+
+=item * the interactive methods
+
+=item * ...
+
+=back
+
+if you want to do a kickstart file, you just have to add all the required fields (see for example
+the variable $default)
+
+=cut
 #-#######################################################################################
 $o = $::o = {
 #    bootloader => { linear => 0, message => 1, timeout => 5, restricted => 0 },
@@ -77,21 +99,40 @@ $o = $::o = {
 
 };
 
+=head1 Steps Navigation
+
+=over
+
+=cut
 
 sub installStepsCall {
     my ($o, $auto, $fun, @args) = @_;
     $fun = "install::steps::$fun" if $auto;
     $o->$fun(@args);
 }
+
+=item getNextStep($o)
+
+Returns next step
+
+=cut
+
 sub getNextStep {
     my ($o) = @_;
     find { !$o->{steps}{$_}{done} && $o->{steps}{$_}{reachable} } @{$o->{orderedSteps}};
 }
 
 #-######################################################################################
-#- Steps Functions
-#- each step function are called with two arguments : clicked(because if you are a
-#- beginner you can force the the step) and the entered number
+
+=back
+
+=head1 Steps Functions
+
+Each step function are called with two arguments : clicked(because if you are a
+beginner you can force the the step) and the entered number
+
+=cut
+
 #-######################################################################################
 
 #------------------------------------------------------------------------------
@@ -290,9 +331,19 @@ sub exitInstall {
 }
 
 #-######################################################################################
-#- Udev Functions
+
+=head1 Udev Functions
+
+=over
+
+=cut
+
 #-######################################################################################
 
+=item start_udev()
+
+=cut
+
 sub start_udev() {
     return if fuzzy_pidofs('udevd');
 
@@ -305,6 +356,10 @@ sub start_udev() {
     run_program::run("udevadm", "trigger", "--type=devices", "--action=add");
 }
 
+=item stop_udev()
+
+=cut
+
 sub stop_udev() {
     kill 15, fuzzy_pidofs('udevd');
     sleep(2);
@@ -312,7 +367,15 @@ sub stop_udev() {
 }
 
 #-######################################################################################
-#- Other Functions
+
+=back
+
+=head1 Other Functions
+
+=over
+
+=cut
+
 #-######################################################################################
 
 sub init_local_install {
@@ -411,6 +474,12 @@ sub sig_segv_handler() {
     install::steps_auto_install_non_interactive::errorInStep($o, $msg);
 }
 
+=item read_stage1_net_conf() {
+
+Reads back netork configuration done by stage1 (see L<stages>).
+
+=cut
+
 sub read_stage1_net_conf() {
     require network::network;
     #- get stage1 network configuration if any.
@@ -439,6 +508,12 @@ sub read_stage1_net_conf() {
     }
 }
 
+=item parse_args($cfg, $patch)
+
+Parse arguments (which came from either the boot loader command line or its configuration file).
+
+=cut
+
 sub parse_args {
     my ($cfg, $patch);
     my %cmdline = map { 
@@ -566,6 +641,22 @@ sub process_auto_steps() {
     }
 }
 
+=item process_patch($cfg, $patch)
+
+Handle installer live patches:
+
+=over 4
+
+=item * OEM patch (C<install/patch-oem.pl>)
+
+=item * defcfg (the file indicated by the defcfg option)
+
+=item * patch (C<patch> file)
+
+=back
+
+=cut
+
 sub process_patch {
     my ($cfg, $patch) = @_;
     #- oem patch should be read before to still allow patch or defcfg.
@@ -576,7 +667,20 @@ sub process_patch {
 }
 
 #-######################################################################################
-#- MAIN
+
+=item main()
+
+This is the main function, the installer entry point called by runinstall2:
+
+=over 4
+
+=item * initialization
+
+=item * steps
+
+=back
+
+=cut
 #-######################################################################################
 sub main {
     $SIG{SEGV} = \&sig_segv_handler;
@@ -684,8 +788,13 @@ sub main {
     finish_install();
 }
 
+=item real_main() {
+
+Go through the steps cycle
+
+=cut
+
 sub real_main() {
-    #-the main cycle
     MAIN: for ($o->{step} = $o->{steps}{first};; $o->{step} = getNextStep($o)) {
 	$o->{steps}{$o->{step}}{entered}++;
 	$o->enteringStep($o->{step});
@@ -716,6 +825,12 @@ sub real_main() {
     }
 }
 
+=item finish_install() {
+
+Clean up the installer before the final reboot.
+
+=cut
+
 sub finish_install() {
     unlink $install::any::compressed_image_on_disk;
     install::media::clean_postinstall_rpms();
@@ -747,4 +862,8 @@ sub finish_install() {
     print "\n" x 80 if !$::local_install;
 }
 
+=back
+
+=cut
+
 1;
-- 
cgit v1.2.1