Great initiative !
Some thoughts I had when reading your proposal:
2009/4/14 Tom Faulhaber <tomfaulha...@gmail.com>
>
> [This is specifically for contrib authors, but also for anyone whose
> interested.]
>
> There was some discussion (or maybe the wailing and gnashing of teeth)
> about the fact that there's lots of cool functionally coming into
> clojure.contrib but no easily accessible documentation. I had been
> thinking about this already and figured maybe I'd set up the framework
> for fixing it.
>
> My idea is to use the namespace and var metadata to auto-generate a
> set of documentation that has:
> - an overview page that lists the namespaces in contrib and presents a
> summary of each derived from the namespace metadata.
> - each entry on the namespace overview page will have a link to an API
> page for that namespace. That page will be basically like the API page
> on clojure.org.
> - probably should have an index page as well, but I haven't thought
> about it much.
> - an ability to link from a namespace to a custom created piece of
> documentation (like the nice DatalogOverview that Jeffery wrote).
>
> I've written the code that builds (a first cut of) this stuff from the
> namespaces. It uses the following metadata:
>
> On the namespace:
> - :author to supply a string with the author(s) name(s)
> - :wiki-doc to supply a wiki specific doc string (that can include
> wiki markup) or, if that doesn't exist, we fall back to
> - :doc the default doc string
Could this be made a little bit more generic ? (If you find it useful) :
Have a global var *rich-doc-renderers* which holds a map of
type-of-rich-documentation to a map of renderer functions indexed by type of
output (mime/type such as plain/html , plain/text for the :doc ...). This
var could be enriched by libraries willing to contribute new standards :
they would provide in the same time a new type of doc, and also ways to
transform these docs into output formats:
Example of *rich-doc-renderers* "out-of-the-box" could be :
*rich-doc-renderers* { :default { :plain/html some.namespace/some-fn
:plain/text some.namespace/some-other-fn ... } } ; default is what would be
used for clojure / clojure-contrib ;
And we could have a :rich-doc instead of :wiki-doc , with a simple version
(if the default type of rich doc is to be used) and an extended version:
simple version :rich-doc "my rich doc" => the type of formatting content to
be used is :default , one can use the provided renderers for :default
extended version :rich-doc { :type :default :content "my rich doc" } => this
version explicits the type of doc in :content. Of course for the general
case it's not needed, but if a lib implementor wants to enrich
*rich-doc-renderers* with a new set of renderers, it could be interesting ?
One problem I can see with my proposal is that it forces the rendering part
to be an explicit dependency (*rich-doc-renderers* references functions).
Maybe this could be loosened by requiring symbols and not fns in the map ?
Do you thing it's interesting, or overkill ?
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To post to this group, send email to clojure@googlegroups.com
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
-~----------~----~----~----~------~----~------~--~---
