On 10/25/12 1:53 PM, David E. Wheeler wrote:
> I'm thinking of Pod as the precedent here, but I think most of the popular programming language ecosystems offer
somethinglike this (JavaDoc, rdoc, etc.).
The advantage that these programming language ecosystems have is that
they can implement the processors for the documentation format in the
language itself, so it's easy to recommend or enforce a particular
system. I don't think we're going to implement any documentation
processing in SQL, so we'd end up adding some kind of external
dependency, and that's usually tricky.
Also, there are wildly diverging paradigms in use. For example, in
Perl, the convention is one man page per module. In Python, for most
modules you don't get any locally installed documentation by default.
Instead, you're encouraged to upload your stuff to readthedocs.org. All
of these have their advantages, but I think it's too early to tell what
the best convention for a PostgreSQL extension would be.