All classes in a pod are placed together within one page, it would be fine to have the package structure as you have in the java docs.

There's actually no package structure in Fantom - all types within a pod are at the same level hierarchically. Personally I think thats a good thing ;) - but a matter of taste.

I fully agree with Brian on the topic of packages. Discussed in http://fantom.org/sidewalk/topic/17. But I think it would be fine the compiler add some kind of meta data to the compiled types based upon the directory structure of the source code. This meta data then can be used to generated structured documentation/overview of the code.

Andy and I discussed this a bit this past week for organizing the index of a pod, and shot it down. I think the difference between Fan and Java, is that you shouldn't have more than 20 or so classes in a Fan pod. But I still have some ideas about "tagging" or "grouping" classes for documentation search.

Smalltalks have tried various schemes for method categories, and class categories, and packages, and it's a fairly necessary thing when the system isn't tiny. "Small pods" is fine, but then you get proliferation of pods. Separate Env's, so any given Fantom runtime only loads the pods it cares about, may turn out to be an okay way to deal with that.

I also wondered about capturing the source directory structure as a way of categorizing pod classes, but the take-away lesson I got from Smalltalk package systems is, any scheme has to be well-thought and integrated with the whole ecosystem of tooling and libraries, or it falls apart somehow.

I think the difference between Fan and Java, is that you shouldn't have more than 20 or so classes in a Fan pod

Well thats interesting. Because that means that a large system will therefore have lots of pods. $work code has 10,000 classes in the application, something like 500+ pods?

Most importantly, this make me question again whether the single name for the pod name is viable. comAcmeDepartmentProjectPodA, comAcmeDepartmentProjectPodB, comAcmeDepartmentProjectPodC, comAcmeDepartmentProjectPodD, comAcmeDepartmentProjectPodE .... Surely, we want some way to get at a namespace for "all the pods in the project of comAcmeDepartmentProject"?

I would think having more than 100 or 150 pods would be unusual even in a large system. I don't think you can equate number of classes to pods, rather my point was that a well defined pod should have a minimal public API surface area of no more than two dozen or so classes (even if internally you have many more). Also we have to remember that Fantom in general uses much fewer classes than Java.

But over time, especially if we have an online repository, then the number of pods available in the cloud will (hopefully) be very large, and tagging/search criteria will probably definitely be a bonus.

I personally don't think people need to go overboard on uniquifying their pod names. People do that with Java packages, but hardly ever do with the jar file names - and how often have you seen jar file or DLL file name collisions? I personally find the super long Java package names sort of annoying.