From 96da58d5aaeb4224f58a63cd5979862501d161e7 Mon Sep 17 00:00:00 2001
From: Michel Jouvin <jouvin@lal.in2p3.fr>
Date: Tue, 8 Nov 2016 10:45:06 +0100
Subject: [PATCH] functions/filesystem: various cleanups

- See #126 for details
---
 quattor/functions/filesystem.pan | 74 ++++++++++++++++----------------
 1 file changed, 38 insertions(+), 36 deletions(-)

diff --git a/quattor/functions/filesystem.pan b/quattor/functions/filesystem.pan
index 46834463d..9a6fa74e7 100644
--- a/quattor/functions/filesystem.pan
+++ b/quattor/functions/filesystem.pan
@@ -7,24 +7,23 @@
 declaration template quattor/functions/filesystem;
 
 
-############################################################
-# FUNCTION num_of_harddisks
-############################################################
+@documentation{
+    desc = returns the number of hard disk in the configuration
+    arg = none
+}
 function num_of_harddisks = {
   length(value("/hardware/harddisks"));
 };
 
-############################################################
-# FINCTION boot_disk
-#
-# returns the disk where grub must be installed
-############################################################
+@documentation{
+    desc = returns the disk where grub must be installed
+    arg = none
+}
 function boot_disk = {
   base = "/hardware/harddisks";
   dsk = value(base);
-  device = "";
   foreach (i;v;dsk) {
-    path = base+"/"+to_string(i)+"/boot";
+    path = format("%s/%s/boot", base, i);
     if ( exists(to_string(path)) && value(path) ) {
       return(i);
     };
@@ -32,9 +31,11 @@ function boot_disk = {
   null;
 };
 
-# Adds a list of logical volumes to a volume group. See
-# https://twiki.cern.ch/twiki/bin/view/FIOgroup/TsiCDBBlockDevices#Proposed_helper_functions
-# for more details.
+@documentation{
+    desc = Adds a list of logical volumes to a volume group. For more details, see \
+ https://twiki.cern.ch/twiki/bin/view/FIOgroup/TsiCDBBlockDevices#Proposed_helper_functions
+    arg = volume group, list of logical groups to add
+}
 function lvs_add = {
   function_name = 'lvs_add';
   if (length (ARGV) != 2) {
@@ -42,7 +43,7 @@ function lvs_add = {
   };
 
   vg = ARGV[0];
-  lv=ARGV[1];
+  lv = ARGV[1];
 
   foreach (l; sz; lv) {
     SELF[l]["volume_group"] = vg;
@@ -54,7 +55,11 @@ function lvs_add = {
   SELF;
 };
 
-# Adds a list of partitions to a disk. First argument is the holding device. Second argument
+@documentation{
+    desc = Adds a list of partitions to a disk
+    arg = holding device, list of partitions to creatd, optionally id of the extended partition,
+}
+# First argument is the holding device. Second argument
 # is a dict with one entry for each partition. The third argument, if any, is
 # the name of the extended partition to be used. If there is no
 # extended partition, the disk is supposed to have only primary
@@ -71,15 +76,15 @@ function partitions_add = {
  
   pt=ARGV[1];
   if (length (ARGV) == 3) {
-    ep=ARGV[2];
+    ep = ARGV[2];
   } else {
-    ep=undef;
+    ep = undef;
   };
 
   foreach (p; params; pt) {
     if (is_defined (ep)) {
-      ns=matches (p, ".*[^0-9]([0-9]+)$");
-      n=to_long (ns[1]);
+      ns = matches (p, "[^0-9]([0-9]+)$");
+      n = to_long (ns[1]);
       if (n > 4) {
         SELF[p]["type"] = "logical";
       } else if (p == ep) {
@@ -104,18 +109,16 @@ function partitions_add = {
     };
   };
   
-  # Validation stuff might be added here.
   SELF;
 };
 
 
-# Function to modify an existing entry in filesystem list or add it if it doesn't exist yet.
-#
-#          '/system/filesystems' = filesystem_mod(filesystems);
-#
-# Arguments :
-#    - filesystems : list of structure_filesystem entries. If there is only one entry, a structure_filesystem
-#                    (nlist) may be passed as argument. 
+@documentation{
+    desc = modify an existing entry in filesystem list or add it if it doesn't exist yet
+    arg = list of structure_filesystem entries. If there is only one entry, a structure_filesystem \
+ (dict) may be passed as argument
+}
+# Calling sequence: '/system/filesystems' = filesystem_mod(filesystems);
 #
 # For each entry in the list, an entry with the same mountpoint is replaced. If not entry with the
 # same entry already exists, a new entry is added at the end of the list. Thus order of list 'filesystems'
@@ -125,15 +128,15 @@ function filesystem_mod = {
   function_name = 'filesystem_mod';
 
   # Check the argument.  Code below uses fslist as a list of
-  # nlists, each containing file system parameters.
+  # dicts, each containing file system parameters.
   if ( ARGC != 1 ) {
     error(function_name + ': usage: filesystem_mod(filesystems)');
-  } else if ( is_nlist(ARGV[0]) ) {
+  } else if ( is_dict(ARGV[0]) ) {
     fslist = list(ARGV[0]);
   } else if ( is_list(ARGV[0]) ) {
     fslist = ARGV[0];
   } else {
-    error(function_name+': argument must be a list of nlist or a nlist');
+    error(function_name+': argument must be a list of dict or a dict');
   };
 
   # Ensure that SELF exists and is a list.
@@ -176,12 +179,11 @@ function filesystem_mod = {
 };
 
 
-# Function to delete one or more filesystem from the filesystem list.
-#
-#          '/system/filesystems' = filesystem_mod(mountpoints);
-#
-# Arguments :
-#    - mountpoints : one or list of mountpoints (string) to remove from filesystem list.
+@documentation{
+    desc = delete one or more filesystem from the filesystem list
+    arg = one or a list of mountpoints (string) to remove from filesystem list
+}
+# Calling sequence: '/system/filesystems' = filesystem_del(mountpoints);
 #
 # For each mount point, if it is present in the filesystem list, remove it. If it is not
 # present, silently ignore.