/**
- * Check that the directory exists and is writable. Directories need to
- * have execute permissions to be considered a directory by FTP servers, etc.
+ * Validates wether a directory exists and is writable. Furthermore, the directory 
+ * can optionally be created if it does not exist, or be set to writable if it is 
+ * currently not writable.
  *
- * @param $directory A string containing the name of a directory path.
- * @param $mode A Boolean value to indicate if the directory should be created
- *   if it does not exist or made writable if it is read-only.
- * @param $form_item An optional string containing the name of a form item that
- *   any errors will be attached to. This is useful for settings forms that
- *   require the user to specify a writable directory. If it can't be made to
- *   work, a form error will be set preventing them from saving the settings.
- * @return FALSE when directory not found, or TRUE when directory exists.
+ * @param   $directory A string representing the directory path.
+ * @param   $mode an optional bitmask containing the actions, if any, to be carried out 
+ *          on the directory. Any combination of the actions FILE_CREATE_DIRECTORY and 
+ *          FILE_MODIFY_PERMISSIONS is allowed.   
+ * @param   $form_item An optional string containing the name of a form item that
+ *          any errors will be attached to. This is useful when the function is 
+ *          used to validate a directory which path has been entered in a form. 
+ *          An error will consequently prevent form submit handlers from running,
+ *          and instead display the form along with the error messages. 
+ * @return  FALSE if the directory does not exist or is not writable, even after
+ *          any optional actions have been carried out. Otherwise, TRUE will be
+ *          returned.  
  */
 function file_check_directory(&$directory, $mode = 0, $form_item = NULL) {
   $directory = rtrim($directory, '/\\');