#2489 PodDoc errors too verbose

SlimerDude Tue 27 Oct 2015

When browsing through my pod documentation, I get a lot of output in the console that looks like this:

acme::releaseNotes.fandoc [Line 1]: Heading missing anchor id: v1.0.0
acme::releaseNotes.fandoc [Line 1]: Heading missing anchor id: v0.0.8
acme::releaseNotes.fandoc [Line 1]: Heading missing anchor id: v0.0.6
...
acme::pod.fandoc: sys::Err: Broken link: pod:afReflux
acme::pod.fandoc: sys::Err: Broken link: pod:fluxText
acme::pod.fandoc: sys::Err: Broken link: pod:syntax
...

I have no intention of fixing the fandocs because I generate my own anchor ids, and use my own schemes for URIs. But I would like to quiet the console output.

It turns out the output is caused by compilerDoc::DocPodLoader.err() which dumps the errs to std out.

Is there any chance of converting this to a log statement so I have the option of turning it off?

diff -r 0f7e8b34c3fa src/compilerDoc/fan/model/DocPod.fan
--- a/src/compilerDoc/fan/model/DocPod.fan	Thu Oct 22 10:59:27 2015 -0400
+++ b/src/compilerDoc/fan/model/DocPod.fan	Wed Oct 28 00:26:40 2015 +0000
@@ -462,9 +462,9 @@
 
   Void err(Str msg, DocLoc loc, Err? cause := null)
   {
-    // TODO
-    echo("$loc: $msg")
-    if (cause != null) cause.trace
+    log := typeof.pod.log
+    if (log.isWarn)
+      log.warn("$loc: $msg", cause)
   }
 
   File file                     // ctor

brian Wed 28 Oct 2015

Those errors are actually from two different phases. The later for broken links is handled by DocEnv which is designed for you to override and handle link resolution, or you can handle error reporting yourself via errReport function.

The heading is a little more tricky because that API works outside of a DocEnv context. We could potentially look at forcing the DocEnv to be passed in, but not sure how easy that would be.

SlimerDude Thu 29 Oct 2015

look at forcing the DocEnv to be passed in

That works. It's a small change that only affects DocPod, DocPodLoader, and DefaultDocEnvActor:

diff -r 0f7e8b34c3fa src/compilerDoc/fan/model/DocPod.fan
--- a/src/compilerDoc/fan/model/DocPod.fan	Thu Oct 22 10:59:27 2015 -0400
+++ b/src/compilerDoc/fan/model/DocPod.fan	Thu Oct 29 14:32:46 2015 +0000
@@ -13,17 +13,17 @@
 const class DocPod : DocSpace
 {
 
-  ** Load from a zip file.
-  static DocPod load(File file)
+  ** Load from a zip file. 'docEnv' is used for reporting documentation errors.
+  static DocPod load(File file, DocEnv docEnv)
   {
-    return DocPod(file)
+    return DocPod(file, docEnv)
   }
 
   ** Private constructor to copy loader fields
-  @NoDoc new make(File file)
+  @NoDoc new make(File file, DocEnv docEnv)
   {
     this.file = file
-    loader := DocPodLoader(file, this)
+    loader := DocPodLoader(file, this, docEnv)
     zip := Zip.open(file)
     try
     {
@@ -244,10 +244,11 @@
 
 internal class DocPodLoader
 {
-  new make(File file, DocPod pod)
+  new make(File file, DocPod pod, DocEnv docEnv)
    {
-    this.file = file
-    this.pod  = pod
+    this.file   = file
+    this.pod    = pod
+    this.docEnv = docEnv
   }
 
   Void loadMeta(Zip zip)
@@ -462,13 +463,12 @@
 
   Void err(Str msg, DocLoc loc, Err? cause := null)
   {
-    // TODO
-    echo("$loc: $msg")
-    if (cause != null) cause.trace
+    docEnv.err(msg, loc, cause)
   }
 
   File file                     // ctor
   DocPod pod                    // ctor
+  DocEnv docEnv                 // ctor
   [Str:Str]? meta               // load
   Str? name                     // loadMeta
   Str? summary                  // loadMeta
@@ -485,5 +485,3 @@
   Obj[]? toc                    // finishTypes/finishChapters
   DocPodIndex? index            // finishIndex
 }
-
-
diff -r 0f7e8b34c3fa src/compilerDoc/fan/util/DefaultDocEnv.fan
--- a/src/compilerDoc/fan/util/DefaultDocEnv.fan	Thu Oct 22 10:59:27 2015 -0400
+++ b/src/compilerDoc/fan/util/DefaultDocEnv.fan	Thu Oct 29 14:32:46 2015 +0000
@@ -29,7 +29,7 @@
   {
     file := Env.cur.findPodFile(name)
     if (file == null) return null
-    return DocPod.load(file)
+    return DocPod.load(file, this)
   }
 
   private const Actor actor := DefaultDocEnvActor(this)

brian Thu 29 Oct 2015

Its a breaking change, but probably really needs to work that way. I pushed a fix

SlimerDude Thu 29 Oct 2015

Cool, thanks.

Login or Signup to reply.