This feature would be very useful, as I know I spend too much time in re-implementing stuff that exists in contrib. However, contrib isn't the only library that needs to be documented. Besides the doc-string metadata, is there any type of Clojure-doc, similar to Java-doc?
Is there utility to generate HTML docs that is part of Clojure contrib/ core? On Apr 14, 7:37 am, Rich Hickey <richhic...@gmail.com> wrote: > On Apr 13, 11:14 pm, Tom Faulhaber <tomfaulha...@gmail.com> wrote: > > > > > [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? > > The wiki on clojure.contrib's googlecode page is definitely the right > place for the contrib docs, contrib members should please feel free to > use it. That's one of the reasons I moved to googlecode. > > Thanks, > > Rich --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
