Refresh class comments in Microdown package

src/Microdown/ManifestMicrodown.class.st

@@ -1,67 +1,87 @@
 "
-I define a parser and code model for MicroDown.
+I define a parser and a code model for Microdown.
 Microdown is a smaller mardown than but mardown, but it is more extensible. 
 It supports the default markdown features:
-- Header
+- Headers
 - Lists
-- Paragraph
-- Code with arguments: key=val&key2=val2
-- Quote
-- Table
+- Paragraphs
+- Code blocks with arguments: key=val&key2=val2
+- Quotes
+- Tables
 - Emphasis 
 - Figures and links
 
 But also 
 - Environment with arguments
 - Anchors
-- Annotated paragraph
-- Math with arguments
-- and more intra block elements such as extensible markups, raw, math, and references.
+- Annotated paragraphs
+- Math blocks with arguments
+- and more intra block elements such as extensible markup, raw, math, and references.
 
 ### In Pharo Image Syntax Essence in 2 seconds
 
-```language=undefined
+```language=text
 
-	#Header
+ #Header
 
-	```language=Pharo&caption=Beautiful&label=Fig1
-	code
-	```
-	> Boring quote block 
-	> Don't use me!
+ ```language=Pharo&caption=Beautiful&label=Fig1
+ code
+ ```
+ > Boring quote block
+ > Don't use me!
 
-   [Pharo is cool](http://pharo.org)
+ [Pharo is cool](http://pharo.org)
 
-   - item 1
-     1. sub item 1 
-     3. sub item 2
-   - item 2 
+ - item 1
+   1. sub item 1 
+   3. sub item 2
+ - item 2 
 
-  `in text` but for pharo hyper links  to class, method and package
-  `Point`, `Point class`, `Point>>#setX:setY:`, `#’Microdown-Tests’ (for packages)
+ `in text` but for pharo hyper links  to class, method and package
+ `Point`, `Point class`, `Point>>#setX:setY:`, `#'Microdown-Tests'` (for packages)
 ```
 
+Produces:
 
+#Header
+
+```language=Pharo&caption=Beautiful&label=Fig1
+code
+```
+> Boring quote block
+> Don't use me!
+
+[Pharo is cool](http://pharo.org)
+
+- item 1
+  1. sub item 1 
+  3. sub item 2
+- item 2 
+
+`in text` but for pharo hyper links  to class, method and package
+`Point`, `Point class`, `Point>>#setX:setY:`, `#'Microdown-Tests'` (for packages)
+
+***
 
 ### Implementation notes
 
-I follow the design mentioned in [https://github.github.com/gfm](https://github.github.com/gfm), in particular the parsing strategy in appendix A.
+I follow the design mentioned in [https://github.github.com/gfm](https://github.github.com/gfm), in particular the parsing strategy in the appendix.
 
-In short, the strategy is that at any point in time, we might have a number of children of the root which are ""open"". The deepest in open in the tree is called ""current"". All the parents of current are open. 
+In short, the strategy is that at any point in time, we can have a number of children of the root that are ""open"". The deepest in open in the tree is called ""current"". All the parents of current are open.
 
-When a new line is read we do the following:
+When a new line is read, we do the following:
 
 1. Check if the new line can be consumed by current.
-   - as part of this a child of current can be made which can consume the new line
+   - As part of this, a child of current can be made which can consume the new line.
 2. If current cannot consume the new line, we close current, move current to its parent, and repeat 1.
-3. The root node can consume anything, for instance by making new nodes for storing the new line.
-4. The root node is not closed until input is exhausted
+3. The root node can consume anything, for instance by making new nodes to store the new line.
+4. The root node is not closed until input is exhausted.
 
-The other packages in this repository are the extensions made to produce Pillar model. 
-Such packages should be moved in the future to other location (probably pillar itself).
+The other packages in this repository are the extensions made to produce the Pillar model. 
+Such packages should be moved to another location in the future (probably pillar itself).
 
-### Acknowledgments
-I was implemented by S. Ducasse, L. Dargaud and G. Polito. It is based on the work on markdown parsing of K. Osterbye. 
+### Acknowledgements
+I was implemented by S. Ducasse, L. Dargaud and G. Polito. It is based on the work on markdown parsing by K. Osterbye.
 "
 Class {
 	#name : 'ManifestMicrodown',

src/Microdown/MicAbsoluteResourceReference.class.st

@@ -2,7 +2,7 @@
 I represent a superclass for all absolute references.
 A reference will then be resolved and produces a resource.
 
-Common for all absolute references is that they store their reference in a uri (ZnUrl).
+Common to all absolute references is that they store their reference in a URI (`ZnUrl`).
 "
 Class {
 	#name : 'MicAbsoluteResourceReference',

src/Microdown/MicAbstractBlock.class.st

@@ -1,10 +1,10 @@
 "
-I am the abstract node of the block objects generated by `MicroDownParser`.
+I am the abstract node of the block objects generated by `MicrodownParser`.
 
-The root of the parsetree is an instance of `MicRootBlock`.
+The root of the parse tree is an instance of `MicRootBlock`.
 I have a set of children, and an uplink to my parent.
 
-See the comment of `MicroDownParser` for an overview of the algorithm used in building such parse tree.
+See the comment of `MicrodownParser` for an overview of the algorithm used to build such a parse tree.
 "
 Class {
 	#name : 'MicAbstractBlock',

src/Microdown/MicAbstractCodeBlock.class.st

@@ -1,5 +1,5 @@
 "
-I am common class for two extension blocks which at the moment shares the same syntax.
+I am the common class for two extension blocks that currently share the same syntax.
 "
 Class {
 	#name : 'MicAbstractCodeBlock',

src/Microdown/MicAnchorBlock.class.st

@@ -1,10 +1,10 @@
 "
-I'm block that represents an anchor to a section. This way text can refer to the anchor to refer to the section. 
+I'm block that represents an anchor to a section. This way, text can refer to the anchor to refer to the section. 
 
-```
+```language=text
 # A section
 @mylovelySection
-``` 
+```
 "
 Class {
 	#name : 'MicAnchorBlock',

src/Microdown/MicAnchorLinker.class.st

@@ -1,14 +1,13 @@
 "
-I'm a vistor connecting anchors to their target.
-For example in the following situation I will make sure that sec has the header as target.
+I'm a vistor who connects anchors to their target.
+For example, in the following situation, I will make sure that the `sec` label has the header as its target.
 
-```
+```text
 # header
 @sec
 ```
 
-I'm usually invoked in a post parsing phase, so transparent to the user.
-
+I'm usually invoked in a post parsing phase, so it's transparent to the user.
 "
 Class {
 	#name : 'MicAnchorLinker',

src/Microdown/MicAnchorReferenceBlock.class.st

@@ -1,10 +1,10 @@
 "
-I represent a reference to a section, figure, environment. I follow the pattern `*@`, label, `@*`
+I represent a reference to a section, figure, or environment. I follow the pattern `*@`, label, `@*`.
 
-```
+For example:
+```text
 See *@fig1@*
 ```
-
 "
 Class {
 	#name : 'MicAnchorReferenceBlock',

src/Microdown/MicAnnotatedBlock.class.st

@@ -1,15 +1,14 @@
 "
-I represent a paragraph with the title. My title can only contain a string while my body can contain formatted text.
+I represent a paragraph with the title. My title can only contain a string and my body can contain formatted text.
 
 I'm created with `!!paragraph` (such as `@@note` `@@important` in Pillar).
 
-!!note This is important so I used exclamatation mark.
-
-### Known limits. 
+!!note This is important so I used exclamation marks.
+ 
+### Known Limitations 
 We should revisit the implementation because there is something unclear. 
-Currently we cannot add list for example inside a annotatedBlock.
+For example, we cannot currently add lists inside an annotatedBlock.
 See [https://github.com/pillar-markup/MicroDown/issues/54](https://github.com/pillar-markup/MicroDown/issues/54)
-
 "
 Class {
 	#name : 'MicAnnotatedBlock',

src/Microdown/MicAnnotationBlock.class.st

@@ -1,14 +1,14 @@
 "
-I represent an annotation delimted by `{!` and `!}`: a tag with parameters.
+I represent an annotation, a tag with parameters, delimited by `{!` and `!}`.
 
-The following is a citation annotation with as parameters the name variable bound to the string 'Duca99a'.
+The following example is a citation annotation with the name variable bound to the string 'Duca99a' as a parameter.
 
 ```text
 {!citation|name=Duca99a!}
 ```
 
 ```
-MicroDownParser parse: '{!citation|name=Duca99a!}'
+MicrodownParser parse: '{!citation|name=Duca99a!}'
 ```
 "
 Class {

src/Microdown/MicArgumentList.class.st

@@ -1,30 +1,30 @@
 "
 I am intended to provide arguments to annotations, codeblocks and environments. 
-I'm used in figures, code, and math equation for now
+Currently, I'm used in figures, code, and math equation.
 
-In the following anchor=fig1&width=70 is an argument list.
-```
+In the following, `anchor=fig1&width=70` is an argument list.
+```text
 ![this is a caption](figures/f.png anchor=fig1&width=70)
 ```
 
-```
-    ```pharo
-	...
-	```
+```text
+ ```pharo
+ ...
+ ```
 ```
 
-is equivalent to the set pharo as value to the default tag which is for blocks language
+is equivalent to setting `pharo` as the value of the default tag, which for blocks is the language tag.
 
-```
-    ```language=pharo
-	...
-	```
+```text
+ ```language=pharo
+ ...
+ ```
 ```
 
 My syntax is of the following form:
 
 - ` ` defaultArg->initialValue, no other arguments. 
-- `value` defaultArg->value, no otherarguments. 
+- `value` defaultArg->value, no other arguments. 
 - `key=arg[&key=arg]*`, defaultArg->initialValue, but arguments.
 - `value|key=arg[&key=arg]*` defaultArg->value, and arguments.
 "

src/Microdown/MicBlockQuoteBlock.class.st

@@ -1,14 +1,12 @@
 "
-I represent preformatted paragraph indicated by '> ' at the beginning of each my lines. 
+I represent a preformatted paragraph indicated by '> ' at the beginning of each of my lines. 
 I'm like a preformatted in HTML or Pillar '= '.
-Every single line should starts with '> '.
+Every single line should start with '> '.
 
-The semantics of microdown quote block is that blocks (code block, header, lists) are not interpreted inside only formatting.
+The semantics of Microdown quote block is that blocks (code blocks, headers, lists) are not interpreted inside only formatting.
 
-In githubmarkdown the definitions are just super complex and we do not follow them. 
+In GitHub Markdown, the definitions are really complex and we do not follow them. 
 	""A block quote marker consists of 0-3 spaces of initial indent, plus (a) the character > together with a following space, or (b) a single character > not followed by a space.""
-
-
 "
 Class {
 	#name : 'MicBlockQuoteBlock',

src/Microdown/MicCitationBlock.class.st

@@ -1,11 +1,10 @@
 "
-A citation is an inline element that represents a bibliography reference as in LaTeX for example.
+A citation is an inline element that represents a bibliography reference, such as in LaTeX.
 The bibliography will be able to extract its entries from the reference in the citation.
 
-```
+```language=text
 this is a text with a {!citation|ref=Duca99a!}
 ```
-
 "
 Class {
 	#name : 'MicCitationBlock',

src/Microdown/MicCodeBlock.class.st

@@ -1,39 +1,38 @@
 "
-I am a code block. I look like this, starting and ending with three $`
-my 'arguments' is just the text from the fourth character up to the end of line.
+I am a code block. I look like this, starting and ending with three `$`` (backticks).
+My 'arguments' variable is the text starting from the fourth character to the end of the line.
 
-```
- \`\`\`arguments
+```text
+ ```arguments
  line 1
  line 2
  line 3
- \`\`\` 
+ ``` 
 ```
 
-A codeblock does not interpreter its contents. 
-You can however specify different tags such as an anchor and a caption. 
+A codeblock does not interpret its contents. 
+However, you can specify different tags, such as an anchor and a caption. 
 
-```
-	```language=pharo|caption=A method&anchor=method 
-	pharoMotto 
-		^ 'Doing something every is the best way to make progress'
-	```
+```text
+ ```language=pharo|caption=A method&anchor=method 
+ pharoMotto 
+ ^ 'Doing something every day is the best way to make progress'
+ ```
 ```
 
+For now we do not support the use of multiple backticks. The markup is only 3 backticks. If you want to nest codeblocks within codeblocks, you must use an extra space. 
 
-For now we do not support the use of multiple backticks. The markup is only 3 backticks. If you want to embed codeblock inside codeblock you must use an extra space. 
-
-```
+```text
  ```
   ```
   A nested codeblock
   ```
  ```
 ```
 
-#### Implementation thoughts
-The current implementation stores lines in a single text and this is a bad idea because first what if the user use lf in his text!
-Second if we want to treat lines separatedly we have to reparse it. Now we do not need it so this is good but this is just by chance!
+#### Implementation Thoughts
+The current implementation stores lines in a single text and this is a bad idea because first what if the user uses `lf`/`cr` in his text!
+Second if we want to treat lines separately, we have to reparse them. Now we do not need it so this is good but this is just by chance!
 "
 Class {
 	#name : 'MicCodeBlock',

src/Microdown/MicColumnBlock.class.st

@@ -1,10 +1,9 @@
 "
-I'm a bloc element that represents a column. I have one optional argument that is the width of the column. I should be nested in a ColumnsBlock element.
+I'm a block element that represents a column. I have one optional argument that is the width of the column. I should be nested in a ColumnsBlock element.
 
-```
+```language=text
 <!columns
 <!column|width=80
-
 - col 1 item1 a first list
 - col 1 item2 a first list
 !>