Shouldn't there be a place to put a Fandoc comment for the pod itself, maybe in the build.fan file?

That way my little podlist viewer would have something to show at the top level besides just the version and dependencies.

I suggest a sys::Pod.doc field, like sys::Type.doc and sys::Slot.doc, that reflects whatever fandoc is put at the top level in the build file that generates the pod.

//build.fan
**
** This pod does cool stuff, and here's how to use it...
**
class Build : BuildPod
{
  override Void setup()
  {
    podName     = "neat"
    version     = "1.0"
    description = "Neat pod for doing neat stuff"
 ...

Maybe the description could get reflected too, in a Pod.desc field?

Right now we just have the description, which you can reflect via the facets:

fansh> Pod.find("sys").facets.join("\n")
indexFacets: [uriScheme]
description: Fan system runtime
buildTime: 2009-05-20T16:38:53.206-04:00 New_York
buildHost: BLAZE
buildUser: Brian

As part of the symbols feature, I've been toying around with a special "pod.fan" source file:

**
** Fandoc for the pod
**
pod
{
  symbolA := "foo"
  symbolB := "foo"
}

But at the same time, the pod doc itself might better as just an entire fandoc file(s). I'm thinking about using that design to replace the docLib chapters.

Shouldn't there be a place to put a Fandoc comment for the pod itself, maybe in the build.fan file?

I agree it would help to have some top-level documentation to inform users how the parts of a pod fit together. I'd prefer a sys::Uri field on build::BuildPod rather than directly embedding the fandoc in build.fan:

class Build : BuildPod
{
  doc = `pod.doc`
}

I'd definitely encourage a "pod.fan" idea if possible. It doesn't prevent extended documentation either, as that can be referenced from the main pod.fan file.