Improve inline documentation

This was a big one...

Author: aristath

classes/actions/class-content.php

@@ -187,10 +187,23 @@ private function should_skip_saving( $post ) {
 	/**
 	 * Check if there is a recent activity for this post.
 	 *
+	 * Prevents duplicate activity records by checking if a similar activity was already recorded.
+	 * Different activity types use different timeframes:
+	 *
+	 * Update activities (±12 hours):
+	 * - Uses a 24-hour window (±12 hours from modification time) to group related updates
+	 * - Prevents multiple update records when a post is saved repeatedly during editing
+	 * - Example: Editing a post at 3 PM won't create new activities if one exists between 3 AM and 3 AM next day
+	 * - The window accounts for timezone differences and allows one update record per day
+	 *
+	 * Other activities (exact match):
+	 * - Publish, trash, delete, etc. check for exact type/post matches
+	 * - No date window needed since these are discrete, one-time events
+	 *
 	 * @param \WP_Post $post The post object.
 	 * @param string   $type The type of activity (ie publish, update, trash, delete etc).
 	 *
-	 * @return bool
+	 * @return bool True if a recent activity exists (skip recording), false otherwise (record new activity).
 	 */
 	private function is_there_recent_activity( $post, $type ) {
 		// Query arguments.
@@ -200,7 +213,9 @@ private function is_there_recent_activity( $post, $type ) {
 			'data_id'  => (string) $post->ID,
 		];
 
-		// If it's an update add the start and end date. We don't want to add multiple update activities for the same post on the same day.
+		// For updates, use a ±12 hour window to prevent duplicate update records during editing sessions.
+		// This groups all updates within a 24-hour period into a single activity.
+		// Other activity types (publish, trash, delete) don't need a window since they're one-time events.
 		if ( 'update' === $type ) {
 			$query_args['start_date'] = \progress_planner()->get_utils__date()->get_datetime_from_mysql_date( $post->post_modified )->modify( '-12 hours' );
 			$query_args['end_date']   = \progress_planner()->get_utils__date()->get_datetime_from_mysql_date( $post->post_modified )->modify( '+12 hours' );

classes/actions/class-maintenance.php

@@ -134,22 +134,50 @@ protected function create_maintenance_activity( $type ) {
 	}
 
 	/**
-	 * Get the type of the update.
+	 * Get the type of the update from WordPress upgrade_* action options.
 	 *
-	 * @param array $options The options.
+	 * WordPress passes different type values depending on what was updated:
+	 * - 'plugin': Single plugin update via upgrader_process_complete
+	 * - 'theme': Single theme update
+	 * - 'core': WordPress core update
+	 * - 'translation': Language pack update
 	 *
-	 * @return string
+	 * Returns 'unknown' when:
+	 * - The type field is missing from options (shouldn't happen in normal operation)
+	 * - Hook is called incorrectly without proper options
+	 *
+	 * @param array $options {
+	 *     Options array from WordPress upgrader_process_complete action.
+	 *
+	 *     @type string $type   The type of update: 'plugin', 'theme', 'core', 'translation'.
+	 *     @type string $action The action performed: 'update', 'install'.
+	 * }
+	 *
+	 * @return string The update type ('plugin', 'theme', 'core', 'translation', or 'unknown').
 	 */
 	protected function get_update_type( $options ) {
 		return isset( $options['type'] ) ? $options['type'] : 'unknown';
 	}
 
 	/**
-	 * Get the type of the install.
+	 * Get the type of the install from WordPress install action options.
+	 *
+	 * WordPress passes different type values depending on what was installed:
+	 * - 'plugin': New plugin installation
+	 * - 'theme': New theme installation
+	 *
+	 * Returns 'unknown' when:
+	 * - The type field is missing from options
+	 * - Installation fails or is interrupted
+	 *
+	 * @param array $options {
+	 *     Options array from WordPress upgrader_process_complete action.
 	 *
-	 * @param array $options The options.
+	 *     @type string $type   The type of installation: 'plugin' or 'theme'.
+	 *     @type string $action The action performed: 'install'.
+	 * }
 	 *
-	 * @return string
+	 * @return string The install type ('plugin', 'theme', or 'unknown').
 	 */
 	protected function get_install_type( $options ) {
 		return isset( $options['type'] ) ? $options['type'] : 'unknown';

classes/activities/class-query.php

@@ -181,17 +181,32 @@ public function query_activities_get_raw( $args ) {
 			return [];
 		}
 
-		// Remove duplicates. This could be removed in a future release.
+		// Remove duplicate activities and clean up the database.
+		// Duplicates can occur due to race conditions in concurrent processes.
+		// This cleanup routine identifies duplicates by creating a unique key from:
+		// - category (e.g., 'content', 'maintenance')
+		// - type (e.g., 'post_publish', 'plugin_update')
+		// - data_id (e.g., post ID, plugin slug)
+		// - date (Y-m-d format)
+		// When duplicates are found, only the first occurrence is kept, and subsequent
+		// duplicates are permanently deleted from the database.
+		// This could be removed in a future release once all legacy duplicates are cleaned up.
 		$results_unique = [];
 		foreach ( $results as $key => $result ) {
+			// Generate unique key for this activity based on its core identifying attributes.
 			$result_key = $result->category . $result->type . $result->data_id . $result->date; // @phpstan-ignore-line property.nonObject
-			// Cleanup any duplicates that may exist.
+
+			// If we've already seen an activity with this key, it's a duplicate - delete it.
 			if ( isset( $results_unique[ $result_key ] ) ) {
 				$this->delete_activity_by_id( $result->id ); // @phpstan-ignore-line property.nonObject
 				continue;
 			}
-			$results_unique[ $result->category . $result->type . $result->data_id . $result->date ] = $result; // @phpstan-ignore-line property.nonObject
+
+			// First occurrence of this activity - keep it.
+			$results_unique[ $result_key ] = $result;
 		}
+
+		// Return array values to reset numeric keys (0, 1, 2...) after filtering.
 		return \array_values( $results_unique );
 	}
 

classes/admin/class-page.php

@@ -228,20 +228,26 @@ public function enqueue_scripts() {
 	 * @return void
 	 */
 	public function maybe_enqueue_focus_el_script( $hook ) {
+		// Get all registered task providers from the task manager.
 		$tasks_providers  = \progress_planner()->get_suggested_tasks()->get_tasks_manager()->get_task_providers();
 		$tasks_details    = [];
 		$total_points     = 0;
 		$completed_points = 0;
+
+		// Filter providers to only those relevant to the current admin page.
 		foreach ( $tasks_providers as $provider ) {
 			$link_setting = $provider->get_link_setting();
+
+			// Skip tasks that aren't configured for this admin page.
 			if ( ! isset( $link_setting['hook'] ) ||
 				$hook !== $link_setting['hook']
 			) {
 				continue;
 			}
 
+			// Build task details for JavaScript.
 			$details = [
-				'link_setting' => $link_setting,
+				'link_setting' => $link_setting, // Contains selector, hook, and highlight config.
 				'task_id'      => $provider->get_task_id(),
 				'points'       => $provider->get_points(),
 				'is_complete'  => $provider->is_task_completed(),
@@ -254,11 +260,12 @@ public function maybe_enqueue_focus_el_script( $hook ) {
 			}
 		}
 
+		// No tasks for this page - don't enqueue the script.
 		if ( empty( $tasks_details ) ) {
 			return;
 		}
 
-		// Register the scripts.
+		// Enqueue the focus element script with task data.
 		\progress_planner()->get_admin__enqueue()->enqueue_script(
 			'focus-element',
 			[

classes/class-badges.php

@@ -156,35 +156,52 @@ public function clear_content_progress() {
 	}
 
 	/**
-	 * Get the latest completed badge.
+	 * Get the latest completed badge across all badge types.
 	 *
-	 * @return \Progress_Planner\Badges\Badge|null
+	 * Badge selection algorithm:
+	 * 1. Iterates through all badge contexts (content, maintenance, monthly_flat)
+	 * 2. For each badge, checks if it's 100% complete
+	 * 3. Compares completion dates stored in settings to find the most recent
+	 * 4. Returns the badge with the most recent completion date
+	 *
+	 * The completion date is stored in settings when a badge reaches 100% progress:
+	 * - Format: 'Y-m-d H:i:s' (e.g., '2025-10-31 14:30:00')
+	 * - Compared as Unix timestamps for accurate chronological ordering
+	 * - Later completion dates take precedence (>= comparison ensures newer badges win)
+	 *
+	 * This is used to:
+	 * - Display the most recent achievement on the dashboard
+	 * - Trigger celebrations for newly completed badges
+	 * - Track user progress momentum
+	 *
+	 * @return \Progress_Planner\Badges\Badge|null The most recently completed badge, or null if none completed.
 	 */
 	public function get_latest_completed_badge() {
 		if ( $this->latest_completed_badge ) {
 			return $this->latest_completed_badge;
 		}
 
-		// Get the settings for badges.
+		// Get the settings for badges (stores completion dates).
 		$settings = \progress_planner()->get_settings()->get( 'badges', [] );
 
 		$latest_date = null;
 
+		// Loop through all badge contexts to find the most recently completed badge.
 		foreach ( [ 'content', 'maintenance', 'monthly_flat' ] as $context ) {
 			foreach ( $this->$context as $badge ) {
-				// Skip if the badge has no date.
+				// Skip badges that don't have a completion date recorded.
 				if ( ! isset( $settings[ $badge->get_id() ]['date'] ) ) {
 					continue;
 				}
 
 				$badge_progress = $badge->get_progress();
 
-				// Continue if the badge is not completed.
+				// Skip badges that aren't 100% complete.
 				if ( 100 > (int) $badge_progress['progress'] ) {
 					continue;
 				}
 
-				// Set the first badge as the latest.
+				// Initialize with the first completed badge found.
 				if ( null === $latest_date ) {
 					$this->latest_completed_badge = $badge;
 					if ( isset( $settings[ $badge->get_id() ]['date'] ) ) {
@@ -193,7 +210,8 @@ public function get_latest_completed_badge() {
 					continue;
 				}
 
-				// Compare dates.
+				// Compare completion dates as Unix timestamps to find the most recent.
+				// Using >= ensures that if multiple badges complete simultaneously, the last one processed wins.
 				if ( \DateTime::createFromFormat( 'Y-m-d H:i:s', $settings[ $badge->get_id() ]['date'] )->format( 'U' ) >= \DateTime::createFromFormat( 'Y-m-d H:i:s', $latest_date )->format( 'U' ) ) {
 					$latest_date                  = $settings[ $badge->get_id() ]['date'];
 					$this->latest_completed_badge = $badge;

classes/class-base.php

@@ -173,45 +173,86 @@ public function init() {
 	}
 
 	/**
-	 * Magic method to get properties.
-	 * We use this to avoid a lot of code duplication.
+	 * Magic method to dynamically instantiate and cache plugin classes.
 	 *
-	 * Use a double underscore to separate namespaces:
-	 * - get_foo() will return an instance of Progress_Planner\Foo.
-	 * - get_foo_bar() will return an instance of Progress_Planner\Foo_Bar.
-	 * - get_foo_bar__baz() will return an instance of Progress_Planner\Foo_Bar\Baz.
+	 * This method enables lazy-loading of plugin classes using a simple naming convention,
+	 * reducing code duplication and improving performance by instantiating classes only when needed.
 	 *
-	 * @param string $name The name of the property.
-	 * @param array  $arguments The arguments passed to the class constructor.
+	 * Naming convention and transformation rules:
+	 * - Method names must start with 'get_'
+	 * - Single underscore (_) = word boundary, becomes uppercase in class name
+	 * - Double underscore (__) = namespace separator, becomes backslash (\)
 	 *
-	 * @return mixed
+	 * Examples:
+	 * ```
+	 * get_settings()                      → Progress_Planner\Settings
+	 * get_admin__page()                   → Progress_Planner\Admin\Page
+	 * get_activities__query()             → Progress_Planner\Activities\Query
+	 * get_suggested_tasks_db()            → Progress_Planner\Suggested_Tasks_Db
+	 * get_admin__widgets__todo()          → Progress_Planner\Admin\Widgets\Todo
+	 * ```
+	 *
+	 * Transformation process:
+	 * 1. Remove 'get_' prefix from method name
+	 * 2. Split on '__' to separate namespace parts
+	 * 3. For each part, split on '_', uppercase first letter of each word, rejoin
+	 * 4. Join namespace parts with '\' and prepend 'Progress_Planner\'
+	 *
+	 * Caching:
+	 * - Once instantiated, classes are cached in $this->cached array
+	 * - Subsequent calls return the cached instance (singleton pattern per class)
+	 * - Cache key is the method name without 'get_' prefix
+	 *
+	 * Backwards compatibility:
+	 * - Deprecated method names are mapped in Deprecations::BASE_METHODS
+	 * - Triggers WordPress deprecation notice and redirects to new method
+	 *
+	 * @param string $name      The method name being called (e.g., 'get_admin__page').
+	 * @param array  $arguments Arguments passed to the method (forwarded to class constructor).
+	 *
+	 * @return object|null The instantiated class, cached instance, or null if method doesn't start with 'get_'.
 	 */
 	public function __call( $name, $arguments ) {
+		// Only handle methods starting with 'get_'.
 		if ( 0 !== \strpos( $name, 'get_' ) ) {
-			return;
+			return null;
 		}
+
+		// Extract cache key by removing 'get_' prefix.
 		$cache_name = \substr( $name, 4 );
+
+		// Return cached instance if already instantiated (singleton pattern).
 		if ( isset( $this->cached[ $cache_name ] ) ) {
 			return $this->cached[ $cache_name ];
 		}
 
+		// Transform method name to fully qualified class name.
+		// Step 1: Split on '__' to get namespace parts (e.g., 'admin__page' → ['admin', 'page']).
 		$class_name = \implode( '\\', \explode( '__', $cache_name ) );
+		// Step 2: Split each part on '_', capitalize words, and rejoin.
+		// e.g., 'suggested_tasks_db' → 'Suggested_Tasks_Db'.
+		// Then prepend namespace: 'Progress_Planner\Suggested_Tasks_Db'.
 		$class_name = 'Progress_Planner\\' . \implode( '_', \array_map( 'ucfirst', \explode( '_', $class_name ) ) );
+
+		// Instantiate the class if it exists.
 		if ( \class_exists( $class_name ) ) {
 			$this->cached[ $cache_name ] = new $class_name( $arguments );
 			return $this->cached[ $cache_name ];
 		}
 
-		// Backwards-compatibility.
+		// Handle deprecated method names for backwards compatibility.
 		if ( isset( Deprecations::BASE_METHODS[ $name ] ) ) {
-			// Deprecated method.
+			// Trigger WordPress deprecation notice.
 			\_deprecated_function(
 				\esc_html( $name ),
-				\esc_html( Deprecations::BASE_METHODS[ $name ][1] ),
-				\esc_html( Deprecations::BASE_METHODS[ $name ][0] )
+				\esc_html( Deprecations::BASE_METHODS[ $name ][1] ), // Version deprecated.
+				\esc_html( Deprecations::BASE_METHODS[ $name ][0] )  // Replacement method.
 			);
+			// Call the replacement method.
 			return $this->{Deprecations::BASE_METHODS[ $name ][0]}();
 		}
+
+		return null;
 	}
 
 	/**