Merge nim-works#189

189: doc: reformat comments, add readmes in subdirs r=saem a=haxscramper

Reformat comments to use double hash (to make them visible in
documentation), add readme.rst in compiler subsystem directories.

Mostly closes nim-works#180 although
there might be some bits and pieces that can be formatted better.


Co-authored-by: haxscramper <[email protected]>

compiler/ast/astalgo.nim

@@ -7,9 +7,9 @@
 #    distribution, for details about the copyright.
 #
 
-# Algorithms for the abstract syntax tree: hash tables, lists
-# and sets of nodes are supported. Efficiency is important as
-# the data structures here are used in various places of the compiler.
+## Algorithms for the abstract syntax tree: hash tables, lists
+## and sets of nodes are supported. Efficiency is important as
+## the data structures here are used in various places of the compiler.
 
 import
   ast/[

compiler/ast/nimlexbase.nim

@@ -7,10 +7,10 @@
 #    distribution, for details about the copyright.
 #
 
-# Base Object of a lexer with efficient buffer handling. In fact
-# I believe that this is the most efficient method of buffer
-# handling that exists! Only at line endings checks are necessary
-# if the buffer needs refilling.
+## Base Object of a lexer with efficient buffer handling. In fact
+## I believe that this is the most efficient method of buffer
+## handling that exists! Only at line endings checks are necessary
+## if the buffer needs refilling.
 
 import
   llstream, strutils
@@ -28,12 +28,17 @@ const
   VT* = '\x0B'
 
 const
-  EndOfFile* = '\0'           # end of file marker
-                              # A little picture makes everything clear :-)
-                              #  buf:
-                              #  "Example Text\n ha!"   bufLen = 17
-                              #   ^pos = 0     ^ sentinel = 12
-                              #
+  EndOfFile* = '\0' ##[
+end of file marker
+
+A little picture makes everything clear
+
+.. code-block:: nim
+
+  "Example Text\n ha!"   bufLen = 17
+    ^pos = 0     ^ sentinel = 12
+
+  ]##
   NewLines* = {CR, LF}
 
 type
@@ -42,12 +47,12 @@ type
     buf*: cstring
     bufStorage: string
     bufLen: int
-    stream*: PLLStream        # we read from this stream
-    lineNumber*: int          # the current line number
-                              # private data:
+    stream*: PLLStream        ## we read from this stream
+    lineNumber*: int          ## the current line number
+                              ## private data:
     sentinel*: int
-    lineStart*: int           # index of last line start in buffer
-    offsetBase*: int          # use ``offsetBase + bufpos`` to get the offset
+    lineStart*: int           ## index of last line start in buffer
+    offsetBase*: int          ## use ``offsetBase + bufpos`` to get the offset
 
 
 proc openBaseLexer*(L: var TBaseLexer, inputstream: PLLStream,
@@ -57,13 +62,13 @@ proc closeBaseLexer*(L: var TBaseLexer)
 proc getCurrentLine*(L: TBaseLexer, marker: bool = true): string
 proc getColNumber*(L: TBaseLexer, pos: int): int
 proc handleCR*(L: var TBaseLexer, pos: int): int
-  # Call this if you scanned over CR in the buffer; it returns the
-  # position to continue the scanning from. `pos` must be the position
-  # of the CR.
+  ## Call this if you scanned over CR in the buffer; it returns the
+  ## position to continue the scanning from. `pos` must be the position
+  ## of the CR.
 proc handleLF*(L: var TBaseLexer, pos: int): int
-  # Call this if you scanned over LF in the buffer; it returns the
-  # position to continue the scanning from. `pos` must be the position
-  # of the LF.
+  ## Call this if you scanned over LF in the buffer; it returns the
+  ## position to continue the scanning from. `pos` must be the position
+  ## of the LF.
 # implementation
 
 proc closeBaseLexer(L: var TBaseLexer) =

compiler/ast/nimsets.nim

@@ -7,7 +7,7 @@
 #    distribution, for details about the copyright.
 #
 
-# this unit handles Nim sets; it implements symbolic sets
+## this unit handles Nim sets; it implements symbolic sets
 
 import
   ast/[ast, astalgo, lineinfos, types],

compiler/ast/readme.rst

@@ -0,0 +1,2 @@
+Code lexer and parser as well as associated modules for working with
+generated trees.

compiler/ast/trees.nim

@@ -7,7 +7,7 @@
 #    distribution, for details about the copyright.
 #
 
-# tree helper routines
+## tree helper routines
 
 import
   ast, wordrecg, idents

compiler/ast/treetab.nim

@@ -7,7 +7,7 @@
 #    distribution, for details about the copyright.
 #
 
-# Implements a table from trees to trees. Does structural equivalence checking.
+## Implements a table from trees to trees. Does structural equivalence checking.
 
 import
   hashes, ast, astalgo, types

compiler/ast/types.nim

@@ -7,7 +7,7 @@
 #    distribution, for details about the copyright.
 #
 
-# this module contains routines for accessing and iterating over types
+## this module contains routines for accessing and iterating over types
 
 import
   std/[

compiler/backend/ccgcalls.nim

@@ -7,7 +7,8 @@
 #    distribution, for details about the copyright.
 #
 #
-# included from cgen.nim
+
+## included from cgen.nim
 
 proc canRaiseDisp(p: BProc; n: PNode): bool =
   # we assume things like sysFatal cannot raise themselves