Changed class comments in Renraku and added a comment in Renraku-Help

src/Renraku-Help/RenrakuCritiqueDesignHelp.class.st

@@ -66,7 +66,9 @@ RenrakuCritiqueDesignHelp class >> hierarchy [
 	^ HelpTopic
 		title: 'Class Hierarchy'
 		contents: 
-'ReAbstractCritique is the root of the critiques hierarchy.'
+'ReAbstractCritique is the root of the critiques hierarchy.
+
+ReAbstractCritique inherits from ReProperty which represents an external property of some entity related to a piece of code. It defines a basic interface of a title an and an icon that can be used to display it in a user interface. It also has a source anchor pointing the piece of code.'
 ]
 
 { #category : #accessing }

src/Renraku/ReAbstractCritique.class.st

@@ -1,7 +1,12 @@
 "
-I am an abstract critic class.
+I am an abstract critique class.
 
-My subclasses should define whether they provide a selection interval, or refactory change
+A critique links a quality rule to a source code target. It is the main unit that should be used to provide information to the user.
+
+I specialize the ReProperty class by extracting information from the rule that reported the violation. 
+The #title is extracted from the rule's #name, the #icon based on the rule's #severity and a #description is provided based on the rule's #rationale.
+
+The reference to the critized entity is established through ReSourceAnchor.
 "
 Class {
 	#name : #ReAbstractCritique,

src/Renraku/ReAbstractRule.class.st

@@ -1,7 +1,18 @@
 "
-I an the root of all quality rules rules.
+I am the root of all quality rules rules.
 
-If you want to learn about the features of rules or how to create your own, please read:
+Each rule should provide a short name string returned from the #name method. You also have to override the #rationale method to return a detailed description about the rule. You may also put the rationale in the class comment, as by default #rationale method returns the comment of the rule's class.
+
+The class-side methods #checksMethod, #checksClass, #checksPackage and #checksNode return true if the rule checks methods, classes or traits, packages and AST nodes respectively. Tools will pass entities of the specified type to the rule for checking. 
+
+To check the rule, while there is a default implementation which relies on #basicCheck: and creates an instance of ReTrivialCritique, it is advised to override the #check:forCritiquesDo: method. 
+
+It's a good idea to assign your rule to a specific group. For this override the #group method and return string with the name of the group. While you can use any name you want, maybe you would like to put your rule into one of the existing groups: API Change, API Hints, Architectural, Bugs, Coding Idiom Violation, Design Flaws, Optimization, Potential Bugs, Rubric, SUnit, Style, Unclassified rules.
+
+You can also specify the severity of your rue by returning one of: #information, #warning, or #error symbols from the #severity method.
+
+
+If you want to learn more about the features of rules or how to create your own, please read:
 
 RenrakuRuleHelp readInHelpBrowser
 "
@@ -133,7 +144,8 @@ ReAbstractRule >> check: anEntity [
 
 { #category : #running }
 ReAbstractRule >> check: anEntity forCritiquesDo: aCriticBlock [
-
+	"Accepts an entity and a block which could be evaluated for each detected critique
+	aCriticBlock may accept one argument: the critique object"
 	(self basicCheck: anEntity)
 		ifTrue: [ aCriticBlock cull: (self critiqueFor: anEntity) ]
 ]

src/Renraku/ReProperty.class.st

@@ -1,5 +1,8 @@
 "
-I'm an external property of some entity. I have a source anchor to it…
+I'm an external property of some entity related to a piece of code.
+
+I define a basic interface of a #title an and an #icon that can be used to display it in a user interface
+I also have a source anchor with a reference to the actual class, method, or other source code entity that I am related to.
 "
 Class {
 	#name : #ReProperty,