Add some of the missing doc-comments

evolibs/Form.php

@@ -257,11 +257,17 @@ class FormPage {
 class FormField {
     protected $value = null;
     protected $error = null;
+    /** @var string|null $label */
     protected $label = null;
+    /** @var string|null $name */
     protected $name = null;
+    /** @var string|null $css_class */
     protected $css_class = null;
+    /** @var bool|null $read_only */
     protected $read_only = null;
+    /** @var bool|null $disabled True if the field is supposed to be disabled */
     protected $disabled = null;
+    /** @var array|null $storage */
     private $storage = NULL;
 
     protected function __construct($label) {

inc/common.php

@@ -16,6 +16,12 @@
 /**
  * Functions
  */
+
+ /**
+  * Check if a file exists and is readable and `die()` if it doesnt.
+  * @param string $file
+  * @return void
+  */
 function test_exist($file) {
     if(!file_exists($file)) {
         die("Erreur, vous devez mettre en place le fichier $file !\n");
@@ -25,11 +31,20 @@ function test_exist($file) {
     }   
 }
 
+/**
+ * Redirect the page to $path on the same HOST
+ * @param string $path
+ * @return never
+ */
 function http_redirect($path) {
     header('Location: '.$_SERVER['REQUEST_SCHEME'].'://'.$_SERVER['HTTP_HOST'].$path);
     exit(0);
 }
 
+/**
+ * @param string $filename
+ * @return string
+ */
 function findexts ($filename)
 {
     $filename = strtolower($filename) ;
@@ -39,20 +54,25 @@ function findexts ($filename)
     return $exts;
 } 
 
+/**
+ * Check if the user is a superadmin
+ * @return bool
+ */
 function is_superadmin() {
     global $conf;
     if(!empty($_SESSION['user']) && in_array($_SESSION['user'], $conf['superadmin'])) {
-        return 1;
+        return true;
     } else {
-        return 0;
+        return false;
     }
 }
 
 /**
- * execute a command with sudo
+ * Execute a command with sudo
  * @param string $cmd The command that will be executed.
- * @param ?array $output see $output parameter of exec().
+ * @param array $output output of the command.
- * @param ?int $return_var see $result_code parameter of exec().
+ * @param int $return_var return status of the command.
+ * @return void
  */
 function sudoexec($cmd, &$output, &$return_var) {
     global $conf;
@@ -66,7 +86,8 @@ function sudoexec($cmd, &$output, &$return_var) {
 }
 
 /**
- * Return TRUE is Evoadmin is installed in cluster mode.
+ * Check if Evoadmin is installed in cluster mode
+ * @return boolean
  */
 function is_cluster_mode() {
     global $conf;
@@ -74,7 +95,8 @@ function is_cluster_mode() {
 }
 
 /**
- * Return TRUE is Evoadmin is installed in multi-cluster mode.
+ * Check if Evoadmin is installed in multi-cluster mode.
+ * @return boolean
  */
 function is_mcluster_mode() {
     global $conf;
@@ -83,6 +105,8 @@ function is_mcluster_mode() {
 
 /**
  * Load config file for the specified cluster.
+ * @param string $cluster
+ * @return void
  */
 function load_config_cluster($cluster) {
     global $conf;
@@ -93,8 +117,7 @@ function load_config_cluster($cluster) {
 }
 
 /**
- * Return wether or not this evoadmin install is a multi PHP install
+ * Check if evoadmin install is a multi PHP install
- *
  * @return boolean - True when it's a multi PHP system
  */
 function is_multiphp() {
@@ -103,9 +126,9 @@ function is_multiphp() {
 }
 
 /**
- *  Webadd
+ * Webadd
- *
+ * @param string $command webadd command to run
- * @return boolean - True when it's a multi PHP system
+ * @return array output from the command
  */
 function run_webadd_cmd($command) {
     global $conf;
@@ -133,6 +156,11 @@ if (!(ini_set('include_path', ini_get('include_path')))) {
     require_once 'PEAR.php';
     require_once 'Log.php';
 
+    /**
+     * (simply there to silence a warning)
+     * @var array $oriconf
+     * @var array $localconf
+     */
     // config files
     // (here because need Log PEAR lib)
     test_exist('../conf/connect.php');

lib/letsencrypt.php

@@ -10,7 +10,8 @@ class LetsEncrypt
     const HTTP_CHALLENGE_URL = '/.well-known/acme-challenge/testfile';
 
     /**
-     * create the file used to test the HTTP challenge
+     * Create the file used to test the HTTP challenge
+     * @return void
      */
     private function createFileHttpChallenge()
     {
@@ -19,7 +20,8 @@ class LetsEncrypt
     }
 
     /**
-     * delete the file used to test the HTTP challenge
+     * Delete the file used to test the HTTP challenge
+     * @return void
      */
     private function deleteFileHttpChallenge()
     {
@@ -28,9 +30,9 @@ class LetsEncrypt
     }
 
     /**
-     * generate a CSR
+     * Generate a CSR
      * @param  string $vhost
-     * @param  array $domains
+     * @param  string[] $domains
      * @return boolean
      */
     public function makeCsr($vhost, $domains)
@@ -108,7 +110,7 @@ class LetsEncrypt
 
     /**
      * Query the corresponding IP for each domain
-     * @param  array $domains list of HTTP checked domains
+     * @param  string[] $domains list of HTTP checked domains
      * @return array $valid_dns_domains list of valid domains
      */
     public function checkDNSValidity($domains)
@@ -133,7 +135,7 @@ class LetsEncrypt
     }
 
     /**
-     * check the presence of make-csr and evoacme binaries
+     * Check the presence of make-csr and evoacme binaries
      * @return boolean
      */
     public function isEvoacmeInstalled()
@@ -207,7 +209,7 @@ class LetsEncrypt
     /**
      * Check if the requested domain is included in the certificate
      * @param string $domainRequested
-     * @param array|string $san
+     * @param string[]|string $san
      * @return bool
      */
     public function isDomainIncludedInCert($domainRequested, $san)