Finalized rule and helpers implementation for CommentRequired rule

src/main/atl/analysis.atl

@@ -367,8 +367,8 @@ rule MesureAvoidFieldNameMatchingMethodName(class : java!ClassDeclaration, metho
 	}
 }
 
--- Creates a measure instance for each element that violates the rule : comment required
-rule MeasureCommentRequired(element: java!NamedElement, violatedProperties: Set(String)) {
+-- Creates a measure instance for each element that violates the rule : CommentRequired
+rule MeasureCommentRequired(element: java!BodyDeclaration, violatedProperties: Set(String)) {
 	to
 		om: smm!ObservedMeasure (
 			measure <- commentRequired,
@@ -379,19 +379,31 @@ rule MeasureCommentRequired(element: java!NamedElement, violatedProperties: Set(
 			shortDescription <- 'Denotes whether comments are required (or unwanted) for specific language elements.'
 		),
 		measurement: smm!DirectMeasurement (
-			error <- 'Violated the properties  {' + violatedProperties + '} in Class: ' + element.originalCompilationUnit.name + ' -> ' + element.oclType().name + ': ' + element.modifier.visibility + ' ' + thisModule.getNamedElementName(element)
+			error <- 'Violated the properties  {' + violatedProperties + '} in Class: ' + element.originalCompilationUnit.name + ' -> ' + element.oclType().name + ': ' + element.modifier.visibility + ' ' + thisModule.getBodyDeclarationName(element)
 		)
-	do {
+		do {
 		commentRequired; 
-	}
+		}
 }
 
--- Returns the declaration name of a NamedElement
--- For field declarations, it is contained in "fragments"
-helper def: getNamedElementName(elem: java!NamedElement): String = 
+-- Returns the declaration name of a BodyDeclaration
+-- In FielDeclaration, the attribute 'name' is NULL, this information is contained in "fragments" instead
+helper def: getBodyDeclarationName(elem: java!BodyDeclaration): String = 
 	if (elem.oclIsTypeOf(java!FieldDeclaration)) 
 		then elem.fragments.first().name
 		else elem.name
 	endif
 ;
 
+-- Returns the AnnotationTypeDeclaration corresponding to the given BodyDeclaration
+-- This is necessary because BodyDeclaration.annotations returns Sequence(!IN<unamed>)
+helper def: getAnnotationTypeDeclarationsFromBodyDeclaration(elem: java!BodyDeclaration): Set(java!AnnotationTypeDeclaration) =
+	java!AnnotationTypeDeclaration.allInstances()
+	->select(annotTypeDec | 
+		annotTypeDec.usagesInTypeAccess->exists(usage | 
+			(usage.eContainer().eContainer().name = elem.name)
+			.and(usage.eContainer().eContainer().modifier.visibility = elem.modifier.visibility)
+			.and(usage.eContainer().eContainer().originalCompilationUnit.name = elem.originalCompilationUnit.name))
+	)
+;
+

src/main/atl/documentation.atl

 library documentation;
 
--- Returs a set of measures for each element that violates the rule : comment value
+--------------------------------------------- CommentRequired ---------------------------------------------
+
+-- Returs a set of measures for each element that violates the rule : CommentRequired
 helper def: commentRequired() : Set(smm!Measure) = 
-	java!NamedElement.allInstances()
-		-> select (elem | not elem.oclIsTypeOf(java!Package) and elem.proxy = false)
-		-> select (elem | thisModule.commentRequiredPropertyCustomization().getKeys().contains(elem.oclType().name))
+	
+	java!BodyDeclaration.allInstances()
+	
+		-- Select only elements from local package
+		-> select (elem | elem.proxy = false)
+		
+		-- Select only elements concerned by the CommentRequired properties (eg. methods, fields, class, enum)
+		-> select (elem | thisModule.commentRequiredPropertyDefinitions().getKeys().contains(elem.oclType().name))
+		
+		-- Select those that violate the CommentRequired rule
 		-> select (elem | thisModule.violatesCommentRequired(elem))
+		
+		-- For each element that has violated the rule, create a measure
 		-> collect (elem | thisModule.MeasureCommentRequired(elem, thisModule.violatedCommentRequiredProperties(elem)))
 ;
 
--- Returns true if the given elem violates any of the "comment value" rule properties
-helper def: violatesCommentRequired(elem: java!NamedElement): Boolean =
+-- Returns true if the given elem violates any of the CommentRequired rule properties
+helper def: violatesCommentRequired(elem: java!BodyDeclaration): Boolean =
 
-	-- An element violates a property if there's at least one that's violated and if 
-	-- it doesn't match any 'Ignored' properties
-	(thisModule.commentRequiredPropertyCustomization().get(elem.oclType().name)
+	-- An element violates a property if there's at least one that's violated,
+	(thisModule.commentRequiredPropertyDefinitions().get(elem.oclType().name)
 	->exists(propertyTuple | thisModule.matchesCommentRequiredProperty('Required',elem, propertyTuple)))
+	
+	-- AND IF it doesn't match any 'Ignored' properties
 	.and(
-		-- TO CORRECT
-		not thisModule.commentRequiredPropertyCustomization().get(elem.oclType().name)
+		not thisModule.commentRequiredPropertyDefinitions().get(elem.oclType().name)
 		->exists(propertyTuple | thisModule.matchesCommentRequiredProperty('Ignored',elem, propertyTuple))
 	)
 ;
 
--- Returns the list of violated "comment value" properties as a string
-helper def: violatedCommentRequiredProperties(elem: java!NamedElement): String = 
-	thisModule.commentRequiredPropertyCustomization().get(elem.oclType().name)
+-- Returns the list of violated CommentRequired properties as a string
+helper def: violatedCommentRequiredProperties(elem: java!BodyDeclaration): String = 
+	
+	-- Get the set of property tuples associated to elem by using elem data type as key to the Map
+	thisModule.commentRequiredPropertyDefinitions().get(elem.oclType().name)
+	
+	-- Concatenate to propertyNames : the name of each property rules that matches requirements for elem
 	->select(propertyTuple | thisModule.matchesCommentRequiredProperty('Required',elem, propertyTuple))
 	->iterate (tuple; propertyNames: String = '' |
 		propertyNames.concat(tuple.property+';')
@@ -34,8 +49,8 @@ helper def: violatedCommentRequiredProperties(elem: java!NamedElement): String =
 	
 -- Returns true if the given property tuple applies to the given elem, false otherwise
 helper def: matchesCommentRequiredProperty(
-	value:String,
-	elem: java!NamedElement, 
+	value:String, -- is either 'Required' or 'Ignore'
+	elem: java!BodyDeclaration, 
 	tuple: TupleType(property:String, value:Boolean, modifier: String, annotation: String)): Boolean = 
 	
 	-- Check whether this rule is required
@@ -43,9 +58,8 @@ helper def: matchesCommentRequiredProperty(
 	
 	-- Check the given element has comments
 	.and(not thisModule.hasComments(elem))
-	--(not thisModule.hasComments(elem))
 
-	-- Check correspondance with modifier
+	-- Check correspondance with modifier vibility
 	.and(
 		if (tuple.modifier.isEmpty()) then true
 		else
@@ -56,9 +70,8 @@ helper def: matchesCommentRequiredProperty(
 	.and(
 		if (tuple.annotation.isEmpty()) then true
 		else
-			-- TODO !! Not working
-			 if (elem.annotations
-			 		->exists(annotation | annotation.equals(tuple.annotation)=0)
+			 if (thisModule.getAnnotationTypeDeclarationsFromBodyDeclaration(elem)
+			 		->exists(annotation | annotation.name = tuple.annotation)
 				) then true else false endif
 		endif)
 		
@@ -75,50 +88,65 @@ helper def: matchesCommentRequiredProperty(
 			 ) then true else false endif
 		endif)
 ;
-		
 	
 -- Returns true if the elem has comments, false otherwise
-helper def: hasComments(elem: java!NamedElement): Boolean = 
+helper def: hasComments(elem: java!BodyDeclaration): Boolean = 
 	not elem.comments.isEmpty()
 ;
 
--- Contains the default configuration for the "Comment value" rule
+-- Contains the default configuration for the CommentRequired rule
 -- Can add, delete or modify properties here to customize them just like in PMD
-helper def: commentRequiredPropertyCustomization() : 
-	Map(String, Set(TupleType(property:String, value:String, modifier: String, annotation: String, prefixes: Set(String)))) = Map {
-	
-	-- Configure comment requirement properties for method declarations
-	('MethodDeclaration',
-		Set {
-			Tuple{property='methodWithOverrideCommentRequirement', value='Ignored', modifier='', annotation='Override', prefixes=Set{}},
-			Tuple{property='publicMethodCommentRequirement', value='Required', modifier='public', annotation='', prefixes=Set{}},
-			Tuple{property='protectedMethodCommentRequirement', value='Required', modifier='protected', annotation='', prefixes=Set{}}, 
-			Tuple{property='protectedMethodCommentRequirement', value='Required', modifier='none', annotation='', prefixes=Set{}}, -- protected is also defined as 'none' in the java model
-			Tuple{property='accessorCommentRequirement', value='Ignored', modifier='', annotation='', prefixes=Set{'get','set'}}	
-		}
-	),
-	-- Configure comment requirement properties for field declarations
-	('FieldDeclaration', 
-	 	Set{
-			Tuple{property='fieldCommentRequirement', value='Required', modifier='', annotation='', prefixes=Set{}},
-			Tuple{property = 'serialVersionUIDCommentRequired', value='Ignored', modifier='', annotation='', prefixes=Set{'serialVersionUID'}},
-			Tuple{property = 'serialPersistentFieldsCommentRequired', value='Ignored', modifier='', annotation='', prefixes=Set{'serialPersistentFields'}}
-			
-	 	}
-	),
+helper def: commentRequiredPropertyDefinitions() :
+	Map(
+		String, -- Key 	 -> the name of java element data type
+		Set(	-- Value -> set of property tuples associated to a java element data type 
+			TupleType(				
+				property:String, 		-- Name of the property
+				value:String, 			-- Possible values ['Required','Ignored']
+				modifier: String, 		-- Indicates whether the property concerns 'private', 'protected' or 'public' elements
+				annotation: String, 	-- Indicates whether the property concerns elements with annotations (e.g Override) 
+				prefixes: Set(String)))	-- Filters concerned elements by their prefixes (usefull for getting accesssors or serialVersionUID fields)
+		) = 
+	Map {
 	
-	-- Configure comment requirement properties for class declarations
-	('ClassDeclaration', 
-	 	Set{
-			Tuple{property='headerCommentRequirement', value=true, modifier='', annotation='', prefixes=Set{}}
-	 	}
-	),
-	
-	-- Configure coment requirement properties for enum
-	('EnumDeclaration', 
-	 	Set{
-			Tuple{property='enumCommentRequirement', value=true, modifier='', annotation='', prefixes=Set{}}
-	 	}
-	)
+		-- Configure comment requirement properties for method declarations
+		('MethodDeclaration',
+			Set {
+				Tuple{property='methodWithOverrideCommentRequirement', value='Ignored', modifier='', annotation='Override', prefixes=Set{}},
+				Tuple{property='publicMethodCommentRequirement', value='Required', modifier='public', annotation='', prefixes=Set{}},
+				Tuple{property='protectedMethodCommentRequirement', value='Required', modifier='protected', annotation='', prefixes=Set{}}, 
+				Tuple{property='protectedMethodCommentRequirement', value='Required', modifier='none', annotation='', prefixes=Set{}}, -- protected is also defined as 'none' in the java model
+				Tuple{property='accessorCommentRequirement', value='Ignored', modifier='', annotation='', prefixes=Set{'get','set'}}	
+			}
+		),
+		
+		-- Configure comment requirement properties for field declarations
+		('FieldDeclaration',
+		 	Set{
+				Tuple{property='fieldCommentRequirement', value='Required', modifier='', annotation='', prefixes=Set{}},
+				Tuple{property = 'serialVersionUIDCommentRequired', value='Ignored', modifier='', annotation='', prefixes=Set{'serialVersionUID'}},
+				Tuple{property = 'serialPersistentFieldsCommentRequired', value='Ignored', modifier='', annotation='', prefixes=Set{'serialPersistentFields'}}
+		 		
+				-- Not by default in PMD but just to test genericity of rule customization :
+				-- Tuple{property='protectedFieldCommentRequirement', value='Ignored', modifier='protected', annotation='', prefixes=Set{}},
+				-- Tuple{property='protectedFieldCommentRequirement', value='Ignored', modifier='none', annotation='', prefixes=Set{}}
+			}
+		),
+		
+		-- Configure comment requirement properties for class declarations
+		('ClassDeclaration', 
+		 	Set{
+				Tuple{property='headerCommentRequirement', value='Required', modifier='', annotation='', prefixes=Set{}}
+		 	}
+		),
+		
+		-- Configure comment requirement properties for enums
+		('EnumDeclaration', 
+		 	Set{
+				Tuple{property='enumCommentRequirement', value=true, modifier='', annotation='', prefixes=Set{}}
+		 	}
+		)
 };
 
+-------------------------------------------------------------------------------------------------------------------
+