doc2 improvements

compiler/docgen.nim

@@ -322,12 +322,12 @@ proc generateIndex*(d: PDoc) =
     writeIndexFile(d[], splitFile(options.outFile).dir / 
                         splitFile(d.filename).name & indexExt)
 
-proc writeOutput*(d: PDoc, filename, outExt: string) = 
+proc writeOutput*(d: PDoc, filename, outExt: string, useWarning = false) = 
   var content = genOutFile(d)
   if optStdout in gGlobalOptions:
     writeRope(stdout, content)
   else:
-    writeRope(content, getOutFile(filename, outExt))
+    writeRope(content, getOutFile(filename, outExt), useWarning)
 
 proc CommandDoc*() =
   var ast = parseFile(addFileExt(gProjectFull, nimExt))

compiler/docgen2.nim

@@ -22,8 +22,12 @@ type
 
 proc close(p: PPassContext, n: PNode): PNode =
   var g = PGen(p)
-  writeOutput(g.doc, g.filename, HtmlExt)
+  let useWarning = sfMainModule notin g.module.flags
-  generateIndex(g.doc)
+  writeOutput(g.doc, g.filename, HtmlExt, useWarning)
+  try:
+    generateIndex(g.doc)
+  except EIO:
+    nil
 
 proc processNode(c: PPassContext, n: PNode): PNode = 
   result = n

compiler/ropes.nim

@@ -82,7 +82,6 @@ proc prepend*(a: var PRope, b: PRope)
 proc toRope*(s: string): PRope
 proc toRope*(i: BiggestInt): PRope
 proc ropeLen*(a: PRope): int
-proc WriteRope*(head: PRope, filename: string)
 proc writeRopeIfNotEqual*(r: PRope, filename: string): bool
 proc ropeToStr*(p: PRope): string
 proc ropef*(frmt: TFormatStr, args: openarray[PRope]): PRope
@@ -204,13 +203,14 @@ proc writeRope*(f: TFile, c: PRope) =
     assert(it.data != nil)
     write(f, it.data)
 
-proc WriteRope(head: PRope, filename: string) = 
+proc WriteRope*(head: PRope, filename: string, useWarning = false) =
   var f: tfile
   if open(f, filename, fmWrite):
     if head != nil: WriteRope(f, head)
     close(f)
   else:
-    rawMessage(errCannotOpenFile, filename)
+    rawMessage(if useWarning: warnCannotOpenFile else: errCannotOpenFile,
+               filename)
 
 proc ropef(frmt: TFormatStr, args: openarray[PRope]): PRope = 
   var i = 0

compiler/semstmts.nim

@@ -267,7 +267,7 @@ proc semVarOrLet(c: PContext, n: PNode, symkind: TSymKind): PNode =
         GlobalError(a.info, errWrongNumberOfVariables)
       b = newNodeI(nkVarTuple, a.info)
       newSons(b, length)
-      b.sons[length-2] = ast.emptyNode # no type desc
+      b.sons[length-2] = a.sons[length-2] # keep type desc for doc generator
       b.sons[length-1] = def
       addSon(result, b)
     for j in countup(0, length-3):
@@ -286,7 +286,7 @@ proc semVarOrLet(c: PContext, n: PNode, symkind: TSymKind): PNode =
         v.typ = typ
         b = newNodeI(nkIdentDefs, a.info)
         addSon(b, newSymNode(v))
-        addSon(b, ast.emptyNode)        # no type description
+        addSon(b, a.sons[length-2])      # keep type desc for doc generator
         addSon(b, copyTree(def))
         addSon(result, b)
       else: 

compiler/semtypes.nim

@@ -897,7 +897,7 @@ proc semGenericParamList(c: PContext, n: PNode, father: PType = nil): PNode =
           s = newSymS(skType, a.sons[j], c)
           s.typ = newTypeS(tyGenericParam, c)
         of tyExpr:
-          echo "GENERIC EXPR ", a.info.toFileLineCol
+          #echo "GENERIC EXPR ", a.info.toFileLineCol
           # not a type param, but an expression
           # proc foo[x: expr](bar: int) what is this?
           s = newSymS(skGenericParam, a.sons[j], c)

compiler/transf.nim

@@ -703,6 +703,9 @@ proc transform(c: PTransf, n: PNode): PTransNode =
   of nkConstSection:
     # do not replace ``const c = 3`` with ``const 3 = 3``
     return transformConstSection(c, n)
+  of nkTypeSection:
+    # no need to transform type sections:
+    return PTransNode(n)
   of nkVarSection, nkLetSection:
     if c.inlining > 0:
       # we need to copy the variables for multiple yield statements:

doc/advopt.txt

@@ -2,7 +2,6 @@ Advanced commands:
   //compileToC, cc          compile project with C code generator
   //compileToCpp, cpp       compile project to C++ code
   //compileToOC, objc       compile project to Objective C code
-  //doc2                    generate the documentation for the whole project
   //rst2html                convert a reStructuredText file to HTML
   //rst2tex                 convert a reStructuredText file to TeX
   //buildIndex              build an index for the whole documentation
@@ -65,4 +64,3 @@ Advanced options:
                             value = number of processors (0 for auto-detect)
   --verbosity:0|1|2|3       set Nimrod's verbosity level (0 is default)
   -v, --version             show detailed version information
-

doc/basicopt.txt

@@ -4,6 +4,7 @@ Usage::
 Command:
   //compile, c                compile project with default code generator (C)
   //doc                       generate the documentation for inputfile
+  //doc2                      generate the documentation for the whole project
   //i                         start Nimrod in interactive mode (limited)
 
 Arguments:
@@ -33,4 +34,3 @@ Options:
   -r, --run                 run the compiled program with given arguments
   --advanced                show advanced command line switches
   -h, --help                show this help
-

todo.txt

@@ -1,8 +1,6 @@
 version 0.9.0
 =============
 
-- change how comments are part of the AST
-
 Debug GC session:
 - bug: stress testing basic method example (eval example) 
   without ``-d:release`` leaks memory?
@@ -25,7 +23,6 @@ New pragmas:
 - document 'do' notation
 - unsigned ints and bignums; requires abstract integer literal type: 
   use tyInt+node for that
-- document nimdoc properly finally
 - rethink the syntax: distinction between expr and stmt is unfortunate; 
   indentation handling is quite complex too; problem with exception handling
   is that often the scope of ``try`` is wrong and apart from that ``try`` is
@@ -44,6 +41,7 @@ Bugs
 version 0.9.XX
 ==============
 
+- document nimdoc properly finally
 - implement a warning message for shadowed 'result' variable
 - implement the high level optimizer
 - change overloading resolution
@@ -61,8 +59,7 @@ version 0.9.XX
 - make pegs support a compile-time option and make c2nim use regexes instead
   per default?
 - 'const' objects including case objects
-- improve docgen to use the semantic pass
+- 'export' feature
-- 'export' feature (requires improved docgen)
 - think about ``{:}.toTable[int, string]()``
 - mocking support with ``tyProxy`` that does:
   o.p(x) --> p(o, x) -->  myMacro(p, o, x)
@@ -103,6 +100,7 @@ Library
 Low priority
 ------------
 
+- change how comments are part of the AST
 - ``with proc `+`(x, y: T): T`` for generic code
 - new feature: ``distinct T with operations``
 - implement the "easy" constructors idea; document destructors

web/news.txt

@@ -101,7 +101,9 @@ Compiler Additions
 - The compiler now generates marker procs that the GC can use instead of RTTI.
   This speeds up the GC quite a bit.
 - The compiler now includes a new advanced documentation generator 
-  via ``doc2``.
+  via the ``doc2`` command. This new generator uses all of the semantic passes
+  of the compiler and can thus generate documentation for symbols hiding in
+  macros.
 
 
 Language Additions