* added PODs to all Perl-modules in lib, documenting those functions that are meant

  to be used by other OpenSLX components (i.e. scripts and plugins)
* applied minor cleanups and convenience extensions to a couple of functions

git-svn-id: http://svn.openslx.org/svn/openslx/openslx/trunk@1722 95ad53e4-c205-0410-b2fa-d234c58c8868

1 files changed, 58 insertions, 6 deletions

diff --git a/lib/OpenSLX/ConfigFolder.pm b/lib/OpenSLX/ConfigFolder.pm
index e8c3ee8f..fd52821e 100644
--- a/lib/OpenSLX/ConfigFolder.pm
+++ b/lib/OpenSLX/ConfigFolder.pm
@@ -8,9 +8,6 @@
 #
 # General information about OpenSLX can be found at http://openslx.org/
 # -----------------------------------------------------------------------------
-# ConfigFolder.pm
-#    - provides utility functions for generation of configuration folders
-# -----------------------------------------------------------------------------
 package OpenSLX::ConfigFolder;
 
 use strict;
@@ -27,12 +24,45 @@ $VERSION = 1.01;
     &createConfigFolderForSystem
 );
 
-################################################################################
-### Module implementation
-################################################################################
+=head1 NAME
+
+OpenSLX::ConfigFolder - implements configuration folder related functionality 
+for OpenSLX.
+
+=head1 DESCRIPTION
+
+This module exports functions that create configuration folders for specific
+system, which will be used by the slxconfig-demuxer when building an initramfs
+for each system.
+
+=cut
+
 use OpenSLX::Basics;
 use OpenSLX::Utils;
 
+=head1 PUBLIC FUNCTIONS
+
+=over
+
+=item B<createConfigFolderForDefaultSystem()>
+
+Creates the configuration folder for the default system.
+
+The resulting folder will be named C<default> and will be created
+in the I<OpenSLX-private-path>C</config>-folder (usually 
+C</var/opt/openslx/config>).
+
+Within that folder, two subfolders, C<initramfs> and C<rootfs> will be created.
+
+In the C<initramfs>-subfolder, two files will be created: C<preinit.local>
+and C<postinit.local>, who are empty stub-scripts meant to be edited by the 
+OpenSLX admin.
+
+The functions returns 1 if any folder or file had to be created and 0 if all the
+required folders & files already existed.
+
+=cut
+
 sub createConfigFolderForDefaultSystem
 {
     my $result = 0;
@@ -81,6 +111,24 @@ sub createConfigFolderForDefaultSystem
     return $result;
 }
 
+=item B<createConfigFolderForSystem($systemName)>
+
+Creates the configuration folder for the system whose name has been given in
+I<$systemName>.
+
+The resulting folder will be named just like the system and will be created
+in the I<OpenSLX-private-path>C</config>-folder (usually 
+C</var/opt/openslx/config>).
+
+In that folder, a single subfolder C<default> will be created (representing
+the default setup for all clients of that system). Within that folder, two
+subfolders, C<initramfs> and C<rootfs> will be created.
+
+The functions returns 1 if any folder had to be created and 0 if all the
+required folders already existed.
+
+=cut
+
 sub createConfigFolderForSystem
 {
     my $systemName = shift || confess "need to pass in system-name!";
@@ -99,4 +147,8 @@ sub createConfigFolderForSystem
     return $result;
 }
 
+=back
+
+=cut
+
 1;