Merge pull request #31 from sectsect/feature/improve-doc-comments

chore: improve doc comments

functions/functions.php

@@ -25,13 +25,14 @@
 }
 
 /**
- * Push the object.
+ * Displays pagination links based on the provided parameters.
  *
- * @since  1.0.5
- * @param  array $paged "Paged".
- * @param  array $pages "Total page numbers".
- * @param  array $range "Range for Pagination".
- * @return void "description".
+ * This function generates HTML for a simple pagination interface, based on the current page,
+ * total number of pages, and the range of pages to display around the current page.
+ *
+ * @param int $paged Current page number, defaults to 1.
+ * @param int $pages Total number of pages, defaults to 1.
+ * @param int $range Number of pages to display around the current page, defaults to 2.
  */
 function google_ss2db_options_pagination( $paged = 1, $pages = 1, $range = 2 ) {
 	$paged     = intval( $paged );
@@ -63,13 +64,14 @@ function google_ss2db_options_pagination( $paged = 1, $pages = 1, $range = 2 ) {
 }
 
 /**
- * Truncate the string (remove characters / words from the middle of the string)
+ * Truncates a string by removing characters from the middle and replacing them with an ellipsis.
+ *
+ * This function is useful for creating previews or shortening strings without losing the beginning
+ * and end of the string. It ensures the string does not exceed the maximum specified length.
  *
- * @param  string $str The input string that you want to truncate in the middle.
- * @param  number $max_chars The "max_chars" parameter is an optional parameter that specifies the maximum
- * number of characters allowed in the string. If this parameter is not provided, the default value is
- * set to 16.
- * @return string
+ * @param string $str The string to truncate.
+ * @param int    $max_chars Maximum number of characters to retain, defaults to 16.
+ * @return string The truncated string.
  */
 function google_ss2db_truncate_middle( $str, $max_chars = 16 ) {
 	$str_length = strlen( $str );

google-spreadsheet-to-db.php

@@ -18,13 +18,10 @@
 define( 'GOOGLE_SS2DB_TABLE_NAME', $wpdb->prefix . 'google_ss2db' );
 
 /**
- * Check the PHP version and give a useful error message if the user's version is less than the required version.
- *
- * @return void "description".
+ * Displays an admin notice if the server's PHP version is below the plugin's required PHP version.
  */
 function google_ss2db_noticephpversionwrong() {
 	global $google_ss2db_minimalrequiredphpversion;
-	// Ensure $google_ss2db_minimalrequiredphpversion is not null and is a string.
 	$required_version = is_null( $google_ss2db_minimalrequiredphpversion ) ? 'unknown' : $google_ss2db_minimalrequiredphpversion;
 	echo '<div class="updated fade">' .
 	__( 'Error: plugin "Google Spreadsheet to DB" requires a newer version of PHP to be running.', 'google_ss2db' ) .
@@ -34,13 +31,12 @@ function google_ss2db_noticephpversionwrong() {
 }
 
 /**
- * Check the PHP version and give a useful error message if the user's version is less than the required version.
+ * Checks the server's PHP version against the plugin's required PHP version.
  *
- * @return boolean "description".
+ * @return bool True if the PHP version is compatible, false otherwise.
  */
 function google_ss2db_phpversioncheck() {
 	global $google_ss2db_minimalrequiredphpversion;
-	// Ensure $google_ss2db_minimalrequiredphpversion is not null before comparison.
 	if ( null === $google_ss2db_minimalrequiredphpversion || version_compare( phpversion(), $google_ss2db_minimalrequiredphpversion ) < 0 ) {
 		add_action( 'admin_notices', 'google_ss2db_noticephpversionwrong' );
 		return false;
@@ -49,9 +45,7 @@ function google_ss2db_phpversioncheck() {
 }
 
 /**
- * The code that runs during plugin activation.
- *
- * @return void "description".
+ * Runs during plugin activation to set up initial settings or structures.
  */
 function activate_google_ss2db() {
 	require_once plugin_dir_path( __FILE__ ) . 'includes/class-google-spreadsheet-to-db-activator.php';
@@ -60,23 +54,21 @@ function activate_google_ss2db() {
 register_activation_hook( __FILE__, 'activate_google_ss2db' );
 
 /**
- * Load the textdomain.
- *
- * @return void "description".
+ * Loads the plugin's text domain for internationalization.
  */
 function google_ss2db_load_textdomain() {
 	load_plugin_textdomain( 'google_ss2db', false, plugin_basename( __DIR__ ) . '/languages' );
 }
 add_action( 'plugins_loaded', 'google_ss2db_load_textdomain' );
 
 /**
- * Add my meta data to row.
+ * Adds a link to the plugin's GitHub page in the plugin meta row.
  *
- * @param  array  $plugin_meta "description".
- * @param  string $plugin_file "description".
- * @param  string $plugin_data "description".
- * @param  string $status      "description".
- * @return statement           "description".
+ * @param array  $plugin_meta An array of the plugin's metadata.
+ * @param string $plugin_file Path to the plugin file relative to the plugins directory.
+ * @param string $plugin_data An array of plugin data.
+ * @param string $status Status of the plugin.
+ * @return array Modified plugin meta data.
  */
 function google_ss2db_row_meta( $plugin_meta, $plugin_file, $plugin_data, $status ) {
 	if ( plugin_basename( __FILE__ ) === $plugin_file ) {

includes/admin.php

@@ -29,9 +29,8 @@
 add_action( 'admin_menu', 'google_ss2db_menu' );
 
 /**
- * Add options page.
- *
- * @return void "description".
+ * Registers the plugin menu in the WordPress admin dashboard.
+ * This function adds a new options page under the Settings menu.
  */
 function google_ss2db_menu() {
 	$page_hook_suffix = add_options_page( 'Google Spreadsheet to DB', '<img src="' . plugins_url( 'assets/images/ss_logo.svg', __DIR__ ) . '" width="12" height="16" /> Google Spreadsheet to DB', 'manage_options', 'google_ss2db_menu', 'google_ss2db_options_page' );
@@ -41,18 +40,17 @@ function google_ss2db_menu() {
 }
 
 /**
- * Enqueue style.
- *
- * @return void "description".
+ * Enqueues custom styles for the admin options page.
+ * This function is hooked to the WordPress admin styles queue.
  */
 function google_ss2db_admin_styles() {
 	wp_enqueue_style( 'admin-options', plugin_dir_url( __DIR__ ) . 'assets/css/admin-options.css', array() );
 }
 
 /**
- * Enqueue script.
- *
- * @return void "description".
+ * Enqueues custom scripts for the admin options page.
+ * This function is hooked to the WordPress admin scripts queue.
+ * It also localizes the script to include nonce and plugin directory URL.
  */
 function google_ss2db_admin_scripts() {
 	wp_enqueue_script( 'google-ss2db-script', plugin_dir_url( __DIR__ ) . 'assets/js/admin-options.js', array( 'jquery' ), null, true );
@@ -67,18 +65,16 @@ function google_ss2db_admin_scripts() {
 }
 
 /**
- * Register setting.
- *
- * @return void "description".
+ * Registers settings for the Google Spreadsheet to DB plugin.
+ * This function adds a new setting to the WordPress settings API.
  */
 function register_google_ss2db_settings() {
 	register_setting( 'google_ss2db-settings-group', 'google_ss2db_dataformat' );
 }
 
 /**
- * Require file.
- *
- * @return void "description".
+ * Includes the options page for the Google Spreadsheet to DB plugin.
+ * This function loads an external PHP class file that handles the display of the options page.
  */
 function google_ss2db_options_page() {
 	require_once plugin_dir_path( __DIR__ ) . 'admin/class-recursivetable.php';

includes/class-google-spreadsheet-to-db-activator.php

@@ -20,9 +20,11 @@
  */
 class Google_Spreadsheet_To_DB_Activator {
 	/**
-	 * Short Description. (use period)
+	 * Activates the plugin by creating or updating the necessary database table.
 	 *
-	 * Long Description.
+	 * This method checks the current installed version of the plugin and updates the database schema if required.
+	 * It creates a new table if it doesn't exist or updates the existing table to match the new schema version.
+	 * This ensures that the plugin's database table is always up to date with the current version.
 	 *
 	 * @since    1.0.0
 	 */

includes/class-google-spreadsheet-to-db-query.php

@@ -1,10 +1,12 @@
 <?php
 /**
- * Fired during plugin activation
+ * Handles database queries for the Google Spreadsheet to DB plugin.
  *
- * @link       https://www.ilovesect.com/
- * @since      1.0.2
+ * This class is responsible for constructing and executing SQL queries based on specified parameters.
+ * It supports filtering, sorting, and pagination of the results. The class is typically initialized
+ * during the plugin's activation to set up necessary configurations.
  *
+ * @since      1.0.2
  * @package    Google_Spreadsheet_to_DB
  * @subpackage Google_Spreadsheet_to_DB/includes
  */
@@ -21,13 +23,18 @@
 class Google_Spreadsheet_To_DB_Query {
 
 	/**
-	 * Short Description. (use period)
+	 * Constructor for the Google_Spreadsheet_To_DB_Query class.
+	 * Initializes the query object with specified or default parameters.
 	 *
-	 * Long Description.
+	 * @param array $args {
+	 *     Optional. Array of query parameters to override defaults.
 	 *
-	 * @since  1.0.2
-	 * @param  array $args "description".
-	 * @return void "description".
+	 *     @type array  $where   Conditions for filtering the query.
+	 *     @type string $orderby Column by which to order the results.
+	 *     @type string $order   Direction to order the results (ASC or DESC).
+	 *     @type int    $limit   Maximum number of results to retrieve.
+	 *     @type int    $offset  Number of results to skip.
+	 * }
 	 */
 	public function __construct( $args = array() ) {
 		$defaults = array(
@@ -42,20 +49,20 @@ public function __construct( $args = array() ) {
 	}
 
 	/**
-	 * Push the object.
+	 * Sets the internal data object based on provided query parameters.
+	 * Converts the array to a JSON object for internal processing.
 	 *
-	 * @since  1.0.2
-	 * @param  array $d "description".
-	 * @return void "description".
+	 * @param array $d The array of query parameters.
 	 */
 	public function setobject( $d ) {
 		$this->data = json_decode( json_encode( $d ) );
 	}
 
 	/**
-	 * Get the rows.
+	 * Retrieves rows from the database based on the query parameters set in the data object.
+	 * Constructs a SQL query dynamically based on conditions such as where, order, and limit.
 	 *
-	 * @return array "description".
+	 * @return array An array of stdClass objects representing each row returned by the query.
 	 */
 	public function getrow() {
 		global $wpdb;

includes/delete.php

@@ -1,9 +1,12 @@
 <?php
 /**
- * The file that defines the core plugin class
+ * Handles the deletion of data entries from the database.
  *
- * A class definition that includes attributes and functions used across both the
- * public-facing side of the site and the admin area.
+ * This script is triggered via a POST request and is responsible for deleting entries
+ * from a specified database table. It checks for a valid nonce to secure the request,
+ * verifies the request method is POST, and confirms the presence of an 'id' in the POST data.
+ * If any of these checks fail, the script will terminate the execution and return an error.
+ * On successful deletion, it returns the result and the ID of the deleted entry in JSON format.
  *
  * @link       https://github.com/sectsect/
  * @since      1.0.0

includes/save.php

@@ -33,11 +33,11 @@
 }
 
 /**
- * Detect to have specific spreadsheet.
+ * Checks if a specific sheet exists within a list of sheets.
  *
- * @param  array  $sheets_list "Array of Spreadsheets".
- * @param  string $sheet_name "Spreadsheet name".
- * @return boolean "description".
+ * @param array  $sheets_list An array of sheet objects.
+ * @param string $sheet_name The name of the sheet to check for.
+ * @return bool Returns true if the sheet exists, false otherwise.
  */
 function exist_sheet( $sheets_list, $sheet_name ) {
 	foreach ( $sheets_list as $sheet ) {
@@ -49,9 +49,9 @@ function exist_sheet( $sheets_list, $sheet_name ) {
 }
 
 /**
- * Returns an authorized API client.
+ * Creates and returns a Google_Client authorized for Google Sheets and Drive APIs.
  *
- * @return Google_Client the authorized client object
+ * @return Google_Client The authorized client object.
  */
 function get_client() {
 	$client_secret = ( defined( 'GOOGLE_SS2DB_CLIENT_SECRET_PATH' ) ) ? GOOGLE_SS2DB_CLIENT_SECRET_PATH : '';
@@ -67,13 +67,13 @@ function get_client() {
 }
 
 /**
- * Get the Google Spreadsheet Data.
+ * Retrieves data from a specified Google Spreadsheet.
  *
- * @param  string $worksheetid "Spreadsheet ID".
- * @param  string $worksheetname "Spreadsheet name".
- * @param  string $sheetname "SingleSheet name on Spreadsheet".
- * @param  string $hasheaderrow "Spreadsheet has a top header row?".
- * @return array "description".
+ * @param string $worksheetid The ID of the Google Spreadsheet.
+ * @param string $worksheetname The name of the Google Spreadsheet.
+ * @param string $sheetname The name of the individual sheet within the Spreadsheet.
+ * @param bool   $hasheaderrow Indicates if the spreadsheet contains a header row.
+ * @return array|bool The spreadsheet data as an associative array if successful, or false if the sheet does not exist.
  */
 function get_value_google_spreadsheet( $worksheetid, $worksheetname, $sheetname, $hasheaderrow ) {
 	// Get the API client and construct the service object.
@@ -124,9 +124,12 @@ function get_value_google_spreadsheet( $worksheetid, $worksheetname, $sheetname,
 }
 
 /**
- * Save Google Spreadsheet Data to DB.
+ * Saves data from a Google Spreadsheet to the database.
  *
- * @return boolean "description".
+ * This function fetches data from a specified Google Spreadsheet and saves it to a custom database table.
+ * The data can be formatted as JSON with or without escaped Unicode characters based on plugin settings.
+ *
+ * @return array Contains details of the operation including the database row ID, date, worksheet identifiers, and operation result.
  */
 function save_spreadsheet() {
 	global $wpdb;