From 7104c40518d3270721044a674877b9503f0dad73 Mon Sep 17 00:00:00 2001
From: Daimona Eaytoy <daimona.wiki@gmail.com>
Date: Sat, 30 Jun 2018 20:35:49 +0200
Subject: [PATCH] Copy levels documentation on AbuseFilterParser

doLevel- functions are currently documented in AFPToken. This patch
copies such comments on docblocks in AbuseFilterParser, the place where
this docs can really be helpful.

Change-Id: I4e47e760a56800faa9b0a1146e0d79f8955dca9a
---
 includes/parser/AFPToken.php          |  2 +-
 includes/parser/AbuseFilterParser.php | 31 +++++++++++++++++++++++++--
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/includes/parser/AFPToken.php b/includes/parser/AFPToken.php
index ea18b755f..957749ae5 100644
--- a/includes/parser/AFPToken.php
+++ b/includes/parser/AFPToken.php
@@ -21,7 +21,7 @@
  * * Entry - catches unexpected characters
  * * Semicolon - ;
  * * Set - :=
- * * Conditionls (IF) - if-then-else-end, cond ? a :b
+ * * Conditionals (IF) - if-then-else-end, cond ? a :b
  * * BoolOps (BO) - &, |, ^
  * * CompOps (CO) - ==, !=, ===, !==, >, <, >=, <=
  * * SumRel (SR) - +, -
diff --git a/includes/parser/AbuseFilterParser.php b/includes/parser/AbuseFilterParser.php
index 451412720..e5bcac39f 100644
--- a/includes/parser/AbuseFilterParser.php
+++ b/includes/parser/AbuseFilterParser.php
@@ -248,7 +248,8 @@ class AbuseFilterParser {
 	}
 
 	/**
-	 * Handles multiple expressions
+	 * Handles multiple expressions delimited by a semicolon
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelSemicolon( &$result ) {
@@ -261,7 +262,7 @@ class AbuseFilterParser {
 	}
 
 	/**
-	 * Handles multiple expressions
+	 * Handles assignments (:=)
 	 *
 	 * @param AFPData &$result
 	 * @throws AFPUserVisibleException
@@ -331,6 +332,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles conditionals: if-then-else and ternary operator
+	 *
 	 * @param AFPData &$result
 	 * @throws AFPUserVisibleException
 	 */
@@ -452,6 +455,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles boolean operators (&, |, ^)
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelBoolOps( &$result ) {
@@ -479,6 +484,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles comparison operators
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelCompares( &$result ) {
@@ -499,6 +506,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles sum-related operations (+ and -)
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelSumRels( &$result ) {
@@ -523,6 +532,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles multiplication-related operations (*, / and %)
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelMulRels( &$result ) {
@@ -542,6 +553,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles powers (**)
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelPow( &$result ) {
@@ -559,6 +572,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles boolean inversion (!)
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelBoolInvert( &$result ) {
@@ -576,6 +591,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles keywords (in, like, rlike, contains, ...)
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelSpecialWords( &$result ) {
@@ -601,6 +618,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles unary plus and minus, like in -5 or -(2 * +2)
+	 *
 	 * @param AFPData &$result
 	 */
 	protected function doLevelUnarys( &$result ) {
@@ -621,6 +640,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles array elements, parsing expressions like array[number]
+	 *
 	 * @param AFPData &$result
 	 * @throws AFPUserVisibleException
 	 */
@@ -648,6 +669,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles brackets, only ( and )
+	 *
 	 * @param AFPData &$result
 	 * @throws AFPUserVisibleException
 	 */
@@ -672,6 +695,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles functions
+	 *
 	 * @param AFPData &$result
 	 * @throws AFPUserVisibleException
 	 */
@@ -737,6 +762,8 @@ class AbuseFilterParser {
 	}
 
 	/**
+	 * Handles the return value
+	 *
 	 * @param AFPData &$result
 	 * @throws AFPUserVisibleException
 	 */