added parameter check to FieldDocComment check, fixes #87 (#444)

* added parameter check to FieldDocComment check, fixes #87
* adjusted autodetection for nested check
* fixed reported position of EmptyBlock check

CHANGELOG.md

@@ -1,14 +1,16 @@
 ## dev branch / next version (2.x.x)
 
 - New check DocCommentStyle [#440](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/440)
-- New check FieldDocComment [#442](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/442)
+- New check FieldDocComment, fixes [#87](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/87) ([#442](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/442) + [#444](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/444))
 - New check TypeDocComment [#440](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/440)
 - Added relaxed mode to ConfigParser, fixes [#441](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/441) ([#443](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/443))
 - Fixed handling of comments between types in ExtendedEmptyLines [#440](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/440)
 - Fixed unittest and coverage reporting for Haxe 4 [#442](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/442)
 - Fixed indentation calculation for functions bodys without curly braces [#443](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/443)
 - Fixed segmentaion faults in NeedBraces and CatchParameterName checks [#443](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/443)
+- Fixed reported position of EmptyBlock check [#444](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/444)
 - Changed message of NestedForLoop check [#443](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/443)
+- Changed autodetection for nested for/if/try checks to start at zero [#444](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/444)
 - Refactored `Checker.getLinePos` to use binary search, reduces runtime from O(N/2) to O(log N) [#439](https://github.com/HaxeCheckstyle/haxe-checkstyle/issues/439)
 
 ## version 2.4.1 (2018-06-14)

src/checkstyle/checks/block/EmptyBlockCheck.hx

@@ -109,14 +109,14 @@ class EmptyBlockCheck extends Check {
 
 	function checkForText(brOpen:TokenTree) {
 		if (brOpen.children.length == 1) {
-			logPos("Empty block should contain a comment or a statement", brOpen.pos);
+			logPos("Empty block should contain a comment or a statement", brOpen.getPos());
 			return;
 		}
 	}
 
 	function checkForStatement(brOpen:TokenTree) {
 		if (brOpen.children.length == 1) {
-			logPos("Empty block should contain a statement", brOpen.pos);
+			logPos("Empty block should contain a statement", brOpen.getPos());
 			return;
 		}
 		var onlyComments:Bool = true;
@@ -129,14 +129,14 @@ class EmptyBlockCheck extends Check {
 					break;
 			}
 		}
-		if (onlyComments) logPos("Block should contain a statement", brOpen.pos);
+		if (onlyComments) logPos("Block should contain a statement", brOpen.getPos());
 	}
 
 	function checkForEmpty(brOpen:TokenTree) {
 		if ((brOpen.children == null) || (brOpen.children.length > 1)) return;
 		var brClose:TokenTree = TokenTreeAccessHelper.access(brOpen).firstChild().is(BrClose).token;
 		if (brClose == null) return;
-		if (brOpen.pos.max != brClose.pos.min) logPos('Empty block should be written as "{}"', brOpen.pos);
+		if (brOpen.pos.max != brClose.pos.min) logPos('Empty block should be written as "{}"', brOpen.getPos());
 	}
 }
 

src/checkstyle/checks/coding/NestedForDepthCheck.hx

@@ -64,7 +64,7 @@ class NestedForDepthCheck extends Check {
 			fixed: [],
 			properties: [{
 				propertyName: "max",
-				values: [for (i in 1...5) i]
+				values: [for (i in 0...5) i]
 			}]
 		}];
 	}

src/checkstyle/checks/coding/NestedIfDepthCheck.hx

@@ -63,7 +63,7 @@ class NestedIfDepthCheck extends Check {
 			fixed: [],
 			properties: [{
 				propertyName: "max",
-				values: [for (i in 1...10) i]
+				values: [for (i in 0...10) i]
 			}]
 		}];
 	}

src/checkstyle/checks/coding/NestedTryDepthCheck.hx

@@ -69,7 +69,7 @@ class NestedTryDepthCheck extends Check {
 			fixed: [],
 			properties: [{
 				propertyName: "max",
-				values: [for (i in 1...5) i]
+				values: [for (i in 0...5) i]
 			}]
 		}];
 	}

src/checkstyle/checks/comments/FieldDocCommentCheck.hx

@@ -187,25 +187,74 @@ class FieldDocCommentCheck extends Check {
 	function checkParams(fieldName:String, token:TokenTree, docToken:TokenTree, text:String) {
 		var popenToken:TokenTree = TokenTreeAccessHelper.access(token).firstChild().firstOf(POpen).token;
 		if (popenToken == null) return;
+		var params:Array<String> = [];
 		if (popenToken.children != null) {
 			for (child in popenToken.children) {
 				switch (child.tok) {
-					case Const(CIdent(ident)): checkParam(fieldName, ident, docToken, text);
+					case Const(CIdent(ident)): params.push(ident);
 					default:
 				}
 			}
 		}
+		checkParamsAndOrder(fieldName, params, docToken, text);
 	}
 
-	function checkParam(fieldName:String, name:String, docToken:TokenTree, text:String) {
-		var search:String = '@param $name ';
-		if (text.indexOf(search) >= 0) return;
-		logPos('Documentation for parameter "$name" of field "$fieldName" missing', docToken.pos);
+	function checkParamsAndOrder(fieldName:String, params:Array<String>, docToken:TokenTree, text:String) {
+		if (params.length <= 0) return;
+		var lines:Array<String> = text.split(checker.lineSeparator);
+		var paramOrder:Array<Int> = [];
+		var missingParams:Array<String> = [];
+		for (param in params) {
+			var search:String = '@param $param ';
+			var index:Int = 0;
+			var found:Bool = false;
+			while (index < lines.length) {
+				var line:String = lines[index++];
+				var pos:Int = line.indexOf(search);
+				if (pos >= 0) {
+					paramOrder.push(index);
+					var desc:String = line.substr(pos + search.length);
+					found = !~/^[\-\s]*$/.match(desc);
+					break;
+				}
+			}
+			if (!found) missingParams.push(param);
+		}
+		if (missingParams.length > 0) logMissingParams(fieldName, missingParams, docToken);
+		else checkParamOrder(fieldName, params, paramOrder, docToken);
+	}
+
+	function checkParamOrder(fieldName:String, params:Array<String>, paramOrder:Array<Int>, docToken:TokenTree) {
+		var start:Int = 0;
+		for (index in 0...paramOrder.length) {
+			var value:Int = paramOrder[index];
+			if (value > start) {
+				start = value;
+				continue;
+			}
+			var param:String = params[index];
+			logPos('Incorrect order of documentation for parameter "$param" of field "$fieldName"', docToken.pos);
+		}
+	}
+
+	function logMissingParams(fieldName:String, params:Array<String>, docToken:TokenTree) {
+		for (param in params) logPos('Documentation for parameter "$param" of field "$fieldName" missing', docToken.pos);
 	}
 
 	function checkReturn(name:String, docToken:TokenTree, text:String) {
 		var search:String = "@return ";
-		if (text.indexOf(search) >= 0) return;
+		var pos:Int = text.indexOf(search);
+		if (pos < 0) {
+			logPos('Documentation for return value of field "$name" missing', docToken.pos);
+			return;
+		}
+		var desc:String = text.substr(pos + search.length);
+		var lines:Array<String> = desc.split(checker.lineSeparator);
+		if (lines.length < 0) {
+			logPos('Documentation for return value of field "$name" missing', docToken.pos);
+			return;
+		}
+		if (!~/^[\-\s]*$/.match(lines[0])) return;
 		logPos('Documentation for return value of field "$name" missing', docToken.pos);
 	}
 

src/checkstyle/checks/whitespace/ListOfEmptyLines.hx

@@ -25,7 +25,7 @@ class ListOfEmptyLines {
 
 	/**
 		checks policy on a single empty line range
-		@param policy - empty lione policy to check
+		@param policy - empty line policy to check
 		@param max - maximum number of empty lines
 		@param range - range to check
 		@param line - line to check

test/checks/comments/FieldDocCommentCheckTest.hx

@@ -118,12 +118,32 @@ class FieldDocCommentCheckTest extends CheckTestCase<FieldDocCommentCheckTests>
 		assertNoMsg(check, ONLY_PUBLIC_CLASS_FIELDS_COMMENTED);
 		assertNoMsg(check, MISSING_PARAM);
 		assertMsg(check, MISSING_RETURN, MSG_DOC_RETURN_FUNC8);
+		assertNoMsg(check, WRONG_PARAM_ORDER);
+		assertNoMsg(check, NO_PARAM_TEXT);
 
 		check.requireParams = true;
 		assertNoMsg(check, ALL_CLASS_FIELDS_COMMENTED);
 		assertNoMsg(check, ONLY_PUBLIC_CLASS_FIELDS_COMMENTED);
 		assertMsg(check, MISSING_PARAM, MSG_DOC_PARAM1_FUNC8);
 		assertMsg(check, MISSING_RETURN, MSG_DOC_RETURN_FUNC8);
+		assertMsg(check, WRONG_PARAM_ORDER, 'Incorrect order of documentation for parameter "param2" of field "func8"');
+		assertMsg(check, NO_PARAM_TEXT, MSG_DOC_PARAM1_FUNC8);
+	}
+
+	@Test
+	public function testRequireReturn() {
+		var check = new FieldDocCommentCheck();
+		check.requireReturn = false;
+		assertNoMsg(check, ALL_CLASS_FIELDS_COMMENTED);
+		assertNoMsg(check, ONLY_PUBLIC_CLASS_FIELDS_COMMENTED);
+		assertNoMsg(check, MISSING_RETURN);
+		assertNoMsg(check, EMPTY_RETURN);
+
+		check.requireReturn = true;
+		assertNoMsg(check, ALL_CLASS_FIELDS_COMMENTED);
+		assertNoMsg(check, ONLY_PUBLIC_CLASS_FIELDS_COMMENTED);
+		assertMsg(check, MISSING_RETURN, MSG_DOC_RETURN_FUNC8);
+		assertMsg(check, EMPTY_RETURN, MSG_DOC_RETURN_FUNC8);
 	}
 
 	@Test
@@ -346,4 +366,38 @@ abstract FieldDocCommentCheckTests(String) to String {
 		var field1:String;
 	}
 	";
+
+	var WRONG_PARAM_ORDER = "
+	class Test2 {
+		/**
+			comment
+			@param param2 - param2
+			@param param1 - param1
+			@return value
+		 **/
+		public function func8(param1:String, param2:String):String {}
+	}
+	";
+
+	var NO_PARAM_TEXT = "
+	class Test2 {
+		/**
+			comment
+			@param param1 -
+			@return value
+		 **/
+		public function func8(param1:String):String {}
+	}
+	";
+
+	var EMPTY_RETURN = "
+	class Test2 {
+		/**
+			comment
+			@param param1 - param1
+			@return
+		 **/
+		public function func8(param1:String):String {}
+	}
+	";
 }