On Thu, 2012-10-25 at 10:31 -0700, David E. Wheeler wrote:
> Any plans to implement a documentation standard for extensions? I would love to see `make install` create the
necessaryman pages and perhaps even HTML (with a link added in the proper place). Anyone given this any thought? Dim?
I think the emerging standard is to have a README.md (or something
similar). This gives enough structure and formatting options for most
extensions.
I don't think we need anything fancy to install and access the
documentation. Most of the time it's on a server, in which case "less"
would do a good job. To me, it's more important to have the
documentation easily accessible over the internet for reference during
development.
That said, we do have a built-in documentation infrastructure, which is
COMMENT. So an extension could have its documentation in its comment
and the comments on its subordinate objects. This may or may not
overlap with what a README would contain, but that depends on the
situation, I think.
