#2484 Missing pod-docs in pod index pages

SlimerDude Sat 17 Oct 2015

Hi, sometimes when viewing a pod's index page I notice it doesn't show the /doc/pod.fandoc file underneath the type list.

After a bit of investigation, I found it's caused by the pod having other arbitrary files in /doc/ that happen to have the .fandoc extension.

When this is the case, the pod is still correctly diagnosed as an API (because as the code comment says, "if the pod has types, it cant be a manual") but the podDoc field is set to null.

I see no reason why normal pods can't have other .fandoc files in /doc/ for as long as they define types, they can't be confused with manual pods.

This patch to compilerDoc::DocPod has the desired behaviour of always looking for a podDoc in all non-manual pods:

diff -r a5949aae81f6 src/compilerDoc/fan/model/DocPod.fan
--- a/src/compilerDoc/fan/model/DocPod.fan	Thu Oct 01 10:34:52 2015 -0400
+++ b/src/compilerDoc/fan/model/DocPod.fan	Sat Oct 17 14:54:01 2015 +0100
@@ -373,12 +373,11 @@
     list := map.vals.sort |a, b| { a.name <=> b.name }
     // if this pod has types, it can't be a manual
-    if (!typeList.isEmpty || list.size <= 1)
+    if (!typeList.isEmpty)
-      if (list.size == 1 && list.first.isPodDoc)
-        this.podDoc = list.first
-      this.chapterMap  = map.toImmutable
-      this.chapterList = list.toImmutable
+      this.podDoc      = list.find { it.isPodDoc } 
+      this.chapterMap  = this.podDoc == null ? Str:DocChapter[:].toImmutable : Str:DocChapter[this.podDoc.name : this.podDoc]
+      this.chapterList = this.podDoc == null ? DocChapter#.emptyList : DocChapter[podDoc]

I've kept chapterMap and chapterList functionality the same (defaulting to a single pod-doc item) but they could just be empty.

brian Sat 17 Oct 2015

There is a lot of assumptions in there about type pods vs chapter pods, plus we have a ton of infrastructure on top of that, so that could be an iffy change. Are you trying to show all the fandoc files in a pod with types? Or just the actual pod.fandoc file?

SlimerDude Sat 17 Oct 2015

Hi, I just want to show the pod.fandoc file.

If a pod has types and contains a pod.fandoc file, then I'd like to show that one file on the index page. For this to happen, the DocPod.podDoc field needs to be set (to pod.fandoc) so it gets rendered.

A quick grep in compilerDoc tells me the DocPod.podDoc field is only used in DocPodIndexRenderer.writeContentApi() so it shouldn't affect anything else.

brian Mon 19 Oct 2015

I pushed a change. The change to the top if block doesn't look correct to me and causes problems in the docs for pods without types that aren't manuals. But I think it should work like you want it to now :)

SlimerDude Tue 20 Oct 2015

Cool, thanks Brian!

Just noticed I queried the same thing in `http://fantom.org/forum/topic/2224` too!

Login or Signup to reply.