[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 On the vars, I use: :wiki-doc and :doc, as above :macro - to indicate if it's a macro :arglists to grab the arglist The last two are set automatically by defn and defmacro. AUTHORS PLEASE NOTE: In order for this to be useful these fields need to be filled in for your contributions. The system will work without it, just not as nicely. The next stage of my plan is to build a robot that watches the subversion repository and updates the doc on every checkin. Therefore the doc will typically correspond to the tip of the tree. To avoid thinking too hard, I'm planning to use the wiki on clojure.contrib's googlecode page because (a) there's almost nothing on it now and (b) it's easy to use subversion to update stuff there. Whether this is the right place long-term is another question that we can worry about once it's running. Does all of this seem like the right direction? Comments? Suggestions? Tom --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
