added some comments and fixed some shapes and examples

src/Roassal3-Examples/RSAbstractExamples.class.st

@@ -14,3 +14,8 @@ Class {
 RSAbstractExamples >> label [
 	^ self className
 ]
+
+{ #category : #accessing }
+RSAbstractExamples >> order [
+	^ 100
+]

src/Roassal3-Examples/RSAnimationExamples.class.st

@@ -2843,4 +2843,9 @@ RSAnimationExamples >> example46Lines [
 
 
 
+]
+
+{ #category : #accessing }
+RSAnimationExamples >> order [
+	^ 1000
 ]

src/Roassal3-Examples/RSBasicAnimationExamples.class.st

@@ -271,3 +271,8 @@ RSBasicAnimationExamples >> example08Markers [
 
 	^ canvas
 ]
+
+{ #category : #accessing }
+RSBasicAnimationExamples >> order [
+	^ 10
+]

src/Roassal3-Examples/RSBasicShapeExamples.class.st

@@ -1043,3 +1043,8 @@ RSBasicShapeExamples >> example44AA [
 			 ].
 	^ canvas
 ]
+
+{ #category : #accessing }
+RSBasicShapeExamples >> order [
+	^ 0
+]

src/Roassal3-Experimental/RSSankeyLine.class.st

@@ -1,5 +1,5 @@
 "
-I represent lines drawn in sankey charts
+I represent lines drawn in sankey charts, these lines have instance variables used by Sankey layout algorithmn
 "
 Class {
 	#name : #RSSankeyLine,

src/Roassal3-SVG-Examples/RSSVGAnimationExamples.class.st

@@ -605,6 +605,11 @@ m 466.15466,362.01006 c 3.19923,26.33245 3.71863,64.39733 2.7468,78.73861 -2.797
 '
 ]
 
+{ #category : #accessing }
+RSSVGAnimationExamples >> order [
+	^ 1001
+]
+
 { #category : #'data - svg' }
 RSSVGAnimationExamples >> puzzlePiece [
 	^ 'M3.739,13.619c0,0,3.516-4.669,5.592-3.642c2.077,1.027-0.414,2.795,1.598,3.719c2.011,0.924,5.048-0.229,4.376-2.899c-0.672-2.67-1.866-0.776-2.798-2.208c-0.934-1.432,4.586-4.59,4.586-4.59s3.361,6.651,4.316,4.911c1.157-2.105,3.193-4.265,5.305-1.025c0,0,1.814,2.412,0.246,3.434s-2.917,0.443-3.506,1.553c-0.586,1.112,3.784,4.093,3.784,4.093s-2.987,4.81-4.926,3.548c-1.939-1.262,0.356-3.364-2.599-3.989c-1.288-0.23-3.438,0.538-3.818,2.34c-0.13,2.709,1.604,2.016,2.797,3.475c1.191,1.457-4.484,4.522-4.484,4.522s-1.584-3.923-3.811-4.657c-2.227-0.735-0.893,2.135-2.917,2.531c-2.024,0.396-4.816-2.399-3.46-4.789c1.358-2.391,3.275-0.044,3.441-1.951C7.629,16.087,3.739,13.619,3.739,13.619z'

src/Roassal3-SVG/RSSVGPathLine.class.st

@@ -1,5 +1,24 @@
 "
-I represent path a complex line from one point to another with an svg path
+I represent path a complex line from one point to another with an svg path.
+
+Here an example:
+```
+RSBasicShapeExamples new example16BasicLinePath inspect
+```
+
+- `svgPath:`. Use a block with one argument, this block should return a String
+```
+svgLine := RSSVGPathLine new.
+svgLine svgPath: [:line | 'M0 0 L200 100L400 0 Z' ].
+svgLine color: Color blue.
+svgLine borderColor: Color black.
+canvas := RSCanvas new.
+canvas add: svgLine.
+canvas
+```
+this block is executed each time you need to redraw the line. As you can see this string is hardcoded, the idea is to use the `line` to create the string with the svg path commands.
+
+But this is only a basic way to draw a custom line. If you will need an special line then you should create a subclass of `RSAbstractLine` then add a methods in `RSAthensRenderer` using the visitor pattern.
 "
 Class {
 	#name : #RSSVGPathLine,
@@ -38,7 +57,7 @@ RSSVGPathLine >> svgPath [
 
 { #category : #accessing }
 RSSVGPathLine >> svgPath: aBlock [
-	"aBlock return a string and recives 2 arguments, the start point and the end point"
+	"aBlock return a string and recives 1 argument, the svg line"
 	svgPath := aBlock 
 
 ]

src/Roassal3-Shapes/RSAbstractControlPointsLine.class.st

@@ -1,5 +1,48 @@
 "
-I am an abstract class for lines with control points
+My instances can have more than 2 control points.
+My Subclasses are: `RSBezier`, `RSPolyline`.
+
+Use `controlPointsController:` to calculate the control points for these lines.
+Check this class `RSAbstractCPController` to get more information about it.
+
+```
+bezier := RSBezier new.
+x := RSBox new.
+y := RSBox new.
+x draggable.
+y draggable.
+bezier from: x.
+bezier to: y.
+bezier controlPointsController: (RSBlockCPController new
+	block: [:line | 
+		{ line from position.
+		line from position x @ line to position y.
+		 line to position }
+		]).
+canvas := RSCanvas new.
+x position: 100@100.
+canvas addAll: { x. y. bezier }.
+```
+In the previous example we use a RSBlockCPController to compute the bezier control points. But this can be complex, then you will need to create a new class to specify the type of bezier or polyline you want.
+
+```
+bezier := RSBezier new.
+controller := RSCustomCPController new.
+boxes := (1 to: 4) collect: [ :each | RSBox new draggable ].
+controller models: boxes.
+
+bezier controlPointsController: controller.
+RSGridLayout new gapSize: 100; on: boxes.
+canvas := RSCanvas new.
+canvas addAll: boxes.
+canvas add: bezier.
+
+canvas
+```
+The previous script allows you to modify the bezier line using movable nodes.
+
+## Markers, and attach points
+Similar to the super class these lines supports markers, and attach points.
 "
 Class {
 	#name : #RSAbstractControlPointsLine,

src/Roassal3-Shapes/RSAbstractDualLine.class.st

@@ -1,5 +1,8 @@
 "
-I am an abtract shape that has an start and one end
+I am an abtract shape that has an start and one end, 2 control points.
+My subclasses are `RSLine` and `RSSVGPathLine`
+
+
 "
 Class {
 	#name : #RSAbstractDualLine,

src/Roassal3-Shapes/RSAbstractLine.class.st

@@ -1,30 +1,54 @@
 "
-I represent the abstract lines that have start and end points
+Lines in roassal can be: straight lines and bezier lines. Here there are som subclasses: `RSLine`, `RSArrowedLine`, `RSBezier`, `RSPolyline`, but you can define more types of lines.
 
-For example:
--=-=-=-=-=-=-=-=-=-=-=-=
-c := RSCanvas new.
+## Examples
+```
+line := RSLine new.
+line startPoint: 0@0.
+line endPoint: 100@100.
+
+bezier := RSBezier new.
+bezier controlPoints: { 0 @ 0. 100@100. 200@0 }.
+```
+More examples:
+```
+RSShapeExamples new example35Lines.
+RSBasicShapeExamples new example12BasicLine.
+RSBasicShapeExamples new example31BorderAttachPointWithOffset.
+```
+
+## Canvas
+Lines interact directly with the canvas(`RSCanvas`), when you add it to the canvas you can access all lines with method `lines`.
 
-circle := RSEllipse new color: Color green; size: 10.
-box := RSBox new color: Color red; size: 10.
-c add: circle; add: box.
+There are two groups of lines in roassal, lines with 2 control points and lines with several control points.
 
-dragMeLabel := RSLabel new text: 'Drag me'.
-c add: dragMeLabel.
-RSLocation new
-	above; center;
-	stick: dragMeLabel on: box.
+## Conection with nodes
+Lines can be conected to a node, an instance of `RSBoundingShape`.
 
-c add: (RSLine new color: Color veryVeryLightGray; from: 0 @ -1000; to: 0 @ 1000).
-c add: (RSLine new color: Color veryVeryLightGray; from: -1000 @ 0; to: 1000 @ 0).
+```
+x := RSBox new.
+y := RSBox new.
+line from: x.
+line to: y.
+```
 
-box translateBy: 50 @ 50.
-box @ RSDraggable.
+Then if you move one box, the line will update its position.
 
-c add: (RSLine new color: Color blue; from: box; to: circle).
+## Attach Points
+In order to calculate the line position related to one connected box, lines use instances of `RSAttachPoint`. An attach point only works with `from:` or `to:` methods.
+```
+line attachPoint: RSVerticalAttach new.
+```
+In the previous script vertical attach point will compute vertical control points for the `from:` and `to:` shapes
+## Markers
+Lines in roassal also have markers, it is a kind of decoration for lines. Check this class `RSTMarkeable`. In a line you can put a decoration for each control point. This decoration is `markerStart:` for the first control point, `markerEnd:` for the last control point. and `markerMiddle:` for middle control points.
+Lines uses `RSMarker`
+```
+shape := RSShapeFactory triangle.
+shape extent: 10@10.
+line markerEnd: shape asMarker.
+```
 
-c
--=-=-=-=-=-=-=-=-=-=-=-=
 "
 Class {
 	#name : #RSAbstractLine,

src/Roassal3-Shapes/RSBoundingShape.class.st

@@ -1,5 +1,12 @@
 "
-My subclasses has an extent and a transformation matrix
+Bounding shapes have encompassing rectangle or bounding box.
+My subclasses are: `RSBitmap`, `RSBox`, `RSCircularShape`, `RSComposite`, `RSLabel`, `RSPieSlice` and `RSSVGPath`
+
+## Instance variables
+- `baseRectangle`, the center of this rectangle is `0@0`, base rectangle contains the basic shape without any transformation.
+- `matrix` is an instance of `AthensAffineTransform`, this matrix handles scalation, rotation, translation and skew operations.
+- `connectedLines`, a collection of lines where this bounding shape is conected. If the shape changes its position, the connected lines will be updated.
+- shouldUpdateLines, 
 "
 Class {
 	#name : #RSBoundingShape,

src/Roassal3-Shapes/RSLine.class.st

@@ -1,9 +1,17 @@
 "
-RSLine describes a line. A line typically links two shapes.
-
-Here is an example:
-
--=-=-=-=
+RSLine describes a line. This example shows how to create a line with basic properties
+
+```
+line := RSLine new.
+line startPoint: 40@30.
+line endPoint: 220@140.
+line color: Color blue.
+line width: 10.
+line dashArray: #(8 4).
+```
+A line typically links two shapes. Here is an example:
+
+```
 | c from to l |
 c := RSCanvas new.
 
@@ -26,9 +34,10 @@ to translateBy: 50 @ 40.
 
 c @ RSCanvasController.
 c
--=-=-=-=
+```
 
-Adding single line can be complex in some situation. You may want to look at RSEdgeBuilder to ease the edge creation. 
+Adding single line can be complex in some situation. You may want to look at `RSLineBuilder` to ease the line creation.
+To get more information read comment of `RSAbstractLine`
 "
 Class {
 	#name : #RSLine,

src/Roassal3-Shapes/RSPolyline.class.st

@@ -10,6 +10,8 @@ c add: polyline.
 
 c open
 ```
+
+Please review comment of `RSAbstractControlPointsLine` and `RSAbstractLine`.
 "
 Class {
 	#name : #RSPolyline,

src/Roassal3-Spec-Examples/RSExamplesBrowser.class.st

@@ -48,21 +48,23 @@ RSExamplesBrowser >> classChanged: cls [
 
 { #category : #private }
 RSExamplesBrowser >> classes [
-	^ RSAbstractExamples withAllSubclasses select: [ :cls | 
-		cls methods anySatisfy: [ :met | 
-			met selector beginsWith: 'example' ] ].
+	^ (RSAbstractExamples withAllSubclasses select: [ :cls | 
+		cls methods anySatisfy: [ :met | met selector beginsWith: 'example' ] ])
+	sorted: [ :a :b | 
+		| x y |
+		x := a new order.
+		y := b new order.
+		x = y
+			ifTrue: [ a name < b name ]
+			ifFalse: [ x < y  ] ]
 ]
 
 { #category : #private }
 RSExamplesBrowser >> computeExamples [
 	selectedClass := self defaultClass.
 	^ (selectedClass methods
 		select: [ :met | met selector beginsWith: 'example' ]
-		) asSortedCollection: [ :a :b |
-		a protocol = b protocol 
-			ifTrue: [ a selector < b selector ]
-			ifFalse: [ a protocol < b protocol ]
-		 ].
+		) asSortedCollection: [ :a :b | a selector < b selector ].
 ]
 
 { #category : #private }
@@ -79,8 +81,8 @@ RSExamplesBrowser >> initializePresenter [
 		help: 'Select the example to view';
 		items: self classes;
 		display: [ :cls | cls name ];
-		displayIcon: [ :cls | cls systemIcon ];
-		whenSelectedItemChangedDo: [ :cls | self classChanged: cls  ].
+		displayIcon: [ :cls | cls iconNamed: cls systemIconName ];
+		whenSelectedItemChangedDo: [ :cls | self classChanged: cls ].
 
 	examples := self computeExamples.
 	index := 1.
@@ -89,9 +91,9 @@ RSExamplesBrowser >> initializePresenter [
 	leftButton action: [ self shiftLeft ].
 	roassalCanvas := self newRoassal.
 	codeEditor := self newCode
-		              withSyntaxHighlight;
-		              withScrollBars;
-		              yourself.
+		withSyntaxHighlight;
+		withScrollBars;
+		yourself.
 	rightButton := self newButton.
 	rightButton label: '>'.
 	rightButton action: [ self shiftRight ].
@@ -110,14 +112,15 @@ RSExamplesBrowser >> run [
 
 { #category : #updated }
 RSExamplesBrowser >> shiftLeft [
-	index = 1 ifTrue: [ ^ self ].
+	index = 1 ifTrue: [ ^ self inform: 'Nothing left' ].
 	index := index - 1.
 	self updateCanvas.
 ]
 
 { #category : #updated }
 RSExamplesBrowser >> shiftRight [
-	index = examples size ifTrue: [ ^ self ].
+	index = examples size
+		ifTrue: [ ^ self inform: 'Nothing Right'].
 	index := index + 1.
 	self updateCanvas.
 ]
@@ -128,7 +131,7 @@ RSExamplesBrowser >> updateCanvas [
 	current := examples at: index.
 	self withWindowDo: [ :window | self initializeWindow: window ].
 	codeEditor text: current sourceCode.
-	codeEditor behavior: selectedClass.
+	codeEditor beForBehavior: selectedClass.
 	[
 		canvas :=  current selector value: selectedClass new.
 		canvas class = RSCanvas ifFalse: [ 

src/Roassal3-Spec-Examples/RSSpecMenu.extension.st

@@ -14,7 +14,7 @@ RSSpecMenu class >> menu07PalettesOn: aBuilder [
 ]
 
 { #category : #'*Roassal3-Spec-Examples' }
-RSSpecMenu classSide >> menu12PalettesOn: aBuilder [
+RSSpecMenu class >> menu12PalettesOn: aBuilder [
 
 	<worldMenu>
 	(aBuilder item: #Roassal3Palettes)