In progress: The documentation of the new behaviour of ppxlib

Signed-off-by: Burnleydev1 <[email protected]>

doc/good-practices.mld

@@ -71,18 +71,24 @@ displaying type, jumping to definition, or showing the list of errors.
 
 {2 Embedding the Errors in the AST}
 
-A common way to report an error is to throw an exception. With this mechanism, when an exception is encountered, the raising rewriter is ignored, the exception is converted into an error by ppxlib, and added to a list of errors, the previous valid AST is used to continue the rewriting process. At the end of the rewriting process, the errors collected are appended at the beginning of the resulting AST. In this mechanism, all the subsequent PPXs are processed before handing the AST over to Merlin.
+A common way to report an error is to throw an exception. With this mechanism, 
+when an exception is encountered, the raising rewriter is ignored, the exception 
+is converted into an error by ppxlib, and added to a list of errors, the previous 
+valid AST is used to continue the rewriting process. 
+At the end of the rewriting process, the errors collected are appended at the 
+beginning of the resulting AST. In this mechanism, all the subsequent PPXs are 
+processed before handing the AST over to Merlin.
 However, this mechanism has some limitations:
 - when an exception is raised, and it can not report multiple errors in a single transformation. 
 - partial code generation since nothing is kept in the transformation when an exception is raised by the rewriter.
 
 A solution to these limitations is to embed the errors in the AST. 
-Embedding the Errors in the AST does this by placing "error extension nodes" at every place where successful code generation was
-impossible. Error extension nodes are special extension nodes [[%ocaml.error
-error_message]] that can be embedded into a valid AST and are interpreted
-later as errors, e.g., by the compiler or Merlin. As all extension nodes,
-they can be put {{:https://ocaml.org/manual/extensionnodes.html}at many places
-in the AST} to replace structure items, expressions, or patterns, for example.
+Embedding the Errors in the AST handles errors by placing "error extension nodes" 
+at every place where successful code generation was impossible. Error extension
+nodes are special extension nodes [[%ocaml.error error_message]] that can be 
+embedded into a valid AST and are interpreted later as errors, e.g., by the 
+compiler or Merlin. As all extension nodes, they can be put {{:https://ocaml.org/manual/extensionnodes.html}
+at many places in the AST} to replace structure items, expressions, or patterns, for example.
 
 For instance, suppose a rewriter is supposed to define a new record type, but
 there is an error in one field’s type generation. In order to have
@@ -197,7 +203,10 @@ If such an exception isn't caught, the PPX driver will return an error code,
 and the exception will be pretty-printed, including the location (that's the
 case when Dune calls the driver). When the driver is spawned with the
 [-embed-errors] or [-as-ppx] flags (that's the case when Merlin calls the driver), 
-the driver will look for located error. If it catches one, it will ignore the raising transformation, and conitnue rewriting from previous valid AST, it will continue this until the rewriting process is finished. At the end of the rewriting process, the errors collected are appended at the beginning of the resulting AST.
+the driver will look for located error. If it catches one, it will ignore the 
+raising transformation, and conitnue rewriting from previous valid AST, it will
+continue this until the rewriting process is finished. At the end of the rewriting 
+process, the errors collected are appended at the beginning of the resulting AST.
 
 Even more in context-free rewriters, raising should be avoided in favour of
 outputting a single error node when finer grained reporting is not needed or