Panelize api.module?

I certainly want to improve the layout of various API pages. We can improve it by adding more templates in Drupal 6, without introducing a dependency on Panels. The main advantage of panels would be the ability to rearrange page components, but I do not see people wanting to do that much.

Ahh, glad you updated this, I'd meant to respond to your initial post, but it slipped off my radar. Based on your response, i think I need to clarify. If the main advantage of introducing Panels would be allowing for customization of the layout, then I'd be completely in agreement - no need to introduce the added complexity of a dependency on Panels to simply take care of layout (with the idea that folks could edit it, which clearly wouldn't be happening). It would be a little harder, but doing it via tpl files would be lighter weight and less complicated to maintain. But layout isn't the big bonus from Panels in this case; tbh, my thinking thus far was that we'd want to use 'static' displays stored in flat files and thereby at least one potentially expensive call to the database in order to optimize performance, at least for a.d.o. That means no point-and-click, drag-and-drop UI - we'd decide on a set of layouts at the outset, then hard-code them. The real advantage of using Panels here would be numerous ways in which we could take advantage of two facets of Panels: the Panels context system, and Panels' compartmentalization (and hence, portability, extensibility, and flexibility).

Panels' context system is really the big seller here. In my mind, good API documentation does a few things:

1. Of course, there's the basics: API docs should present the relevant source code, format and present php docblock documentation (including parameter & return types and descriptions).
2. API docs should be laced with internal links - references to other API functions, code samples, that sort of thing.
3. API docs should provide 'meta-information' about what they're documenting. Some throwaway ideas (let's assume that what we're documenting is a function): how many functions call it & what variation of arguments they use, what kind of cachegrind footprint the function has, warnings/errors raised by coder.module on that function (if any), simpletest routines that involve the function, etc. Hell, I can even picture an algorithm that looks for 'related functions' along the lines of Amazon's 'related products' system; we could find the API docs guiding us to corners of the Drupal code jungle that we ourselves weren't even aware of.

   That's more complex stuff, some of which would be dependent on other as-yet-unbuilt-architecture to generate the relevant data, but it can be encapsulated in panels context as easily, flexibly, and efficiently as the node context plugin that ships with Panels can encapsulate node objects.

4. API docs should also take care not to be overwhelming, something that we really risk if we're jamming all this extra data on a page.

All these nifty possibilities make me think about another thing - throttling. If we're gonna provide snazzy documentation, then we should ensure that some of the snazzier, heavier-duty elements get disabled when the server load gets too high.

All of these things could be done with some fancy footwork in tpl files and writing some creative data-collecting additions in api.module itself. On that, I'll cite the experience of project.module - I often hear regret expressed over using a custom query-and-list system over Views, since that's really what Views _does_. I think it's quite accurate to say that most of the things listed above are really what Panels _does_. Panels1 was primarily a mechanism for handling layout, as you say, but Panels2 is quite another beast; my personal hope is that it will shed the perception of being just a layout engine once more and more modules start exploring just how deep the Panels2 rabbit hole goes. Every single one of those things I listed above can be neatly compartmentalized into some combination of Panels plugins (again, given the availability of the relevant data); doing so abstracts the data collection & organization logic almost entirely from the tpl theming layer, which we can still utilize to fine-tune the final appearance of what Panels has organized and outputted.

Now I'd be the first to admit that there are some points in Panels that are still rough, and that there's definitely some performance optimization to be done. But virtually none of the outstanding bugs that I can think of have anything to do with the actual rendering of content - the only things that come to mind are problems with the page title selection logic (but that's specific to panels_page) and problems generating RSS feeds from views. But the real argument for using Panels here is still that building a system that pulls together disparate but related data, such as what I described in the list above, and organizing it into a general layout on the page, is _the thing_ we try to make Panels good at doing. Really, Panels is best thought of as a structured set rules and processes that retrieve and organize content. The structure makes the system (relatively) easily understood, predictable, and highly extensible - all (obviously) very good things.

Great! I'll commit to staying results-oriented as well on this. Of course for now, I think that being results-oriented means 'a-whole-lot-of-hurry-up-and-wait,' - seems to me that D6 ports are and should be a higher priority for both api and panels. 'Postponed' is definitely the right status...