Add comprehensive Doxygen documentation to get_matching_lines_from_filename()

- Document purpose, parameters, return values, and behavior
- Include practical example with TCP keepalive warnings
- Explain memory-efficient queue-based approach
- Note stream sharing benefits and I/O limitations
- Provide clear contract for function usage and expectations

test/tap/tap/utils.h

@@ -767,7 +767,52 @@ std::pair<size_t,std::vector<line_match_t>> get_matching_lines(
 );
 
 
-// Function to scan last N lines from filename (no stream sharing issues)
+/**
+ * @brief Scan last N lines from a file and find lines matching a regex pattern.
+ *
+ * This function provides memory-efficient scanning of log files by processing only
+ * the last N lines instead of loading the entire file into memory. It uses a queue-based
+ * approach to maintain the most recent lines and applies regex matching to identify
+ * lines containing specific patterns.
+ *
+ * This is particularly useful for TAP tests that need to verify log messages were
+ * written during test execution, allowing efficient examination of recent log entries
+ * without loading entire log files that may be very large.
+ *
+ * @param filename Path to the file to scan
+ * @param regex Regular expression pattern to match against line content
+ * @param get_matches If true, capture and return the matched substrings; if false, only track matching lines
+ * @param max_lines Maximum number of lines from end of file to examine (controls memory usage and focus)
+ *
+ * @return std::pair<size_t, std::vector<line_match_t>> where:
+ *         - first: Number of matches found
+ *         - second: Vector of line_match_t tuples containing match information:
+ *                  * POS: File position (placeholder 0 for this implementation)
+ *                  * LINE: Complete line content that matched the pattern
+ *                  * MATCH: Matched substring if get_matches=true, empty string otherwise
+ *
+ * @note This function avoids stream sharing issues by opening its own file handle,
+ *       making it safe for multiple concurrent calls within the same test.
+ *
+ * @warning This function reads the entire file to extract the last max_lines, so
+ *          very large files will still incur I/O overhead, but memory usage is bounded.
+ *
+ * @example
+ * // Find TCP keepalive warnings in last 10 lines of ProxySQL log
+ * auto [match_count, matches] = get_matching_lines_from_filename(
+ *     "/var/log/proxysql.log",
+ *     ".*WARNING.*tcp_keepalive.*",
+ *     true,
+ *     10
+ * );
+ * if (match_count > 0) {
+ *     // Found TCP keepalive warnings
+ *     for (const auto& match : matches) {
+ *         const string& line = std::get<LINE>(match);
+ *         printf("Warning: %s\n", line.c_str());
+ *     }
+ * }
+ */
 std::pair<size_t,std::vector<line_match_t>> get_matching_lines_from_filename(
 	const std::string& filename, const std::string& regex, bool get_matches, size_t max_lines
 );