Add coments for filter_get_bug_rows_query_clauses

Warn about the use of db_param_push() inside this function and its
implications for caller code.

Signed-off-by: Damien Regad <dregad@mantisbt.org>

Original commit modified: wrapped long lines

core/filter_api.php

@@ -1184,7 +1184,13 @@ function filter_get_bug_rows_result( array $p_query_clauses, $p_count = null, $p
 }
 
 /**
- * Creates an array of formatted query clauses, based on the supplied filter and parameters
+ * Creates an array of formatted query clauses, based on the supplied
+ * filter and parameters.
+ * Note: this function executes db_param_push():
+ *  - If the returned query is not executed, db_param_pop() should be executed
+ *    to clean up the parameter stack
+ *  - If the final query adds db_param() outside of this function,
+ *    they must be added after this function is called.
  * @param array   $p_filter       Filter array object
  * @param integer $p_project_id   Project id to use in filtering.
  * @param integer $p_user_id      User id to use as current user when filtering.

core/history_api.php

@@ -193,6 +193,7 @@ function history_get_range_result_filter( $p_filter, $p_start_time = null, $p_en
 		$t_history_order = $p_history_order;
 	}
 
+	# Note: filter_get_bug_rows_query_clauses() calls db_param_push();
 	$t_query_clauses = filter_get_bug_rows_query_clauses( $p_filter, null, null, null );
 
 	$t_select_string = 'SELECT DISTINCT {bug}.id ';