On Apr 14, 2009, at 5:14, Tom Faulhaber wrote: > 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).
That sounds like an excellent idea! I'd be happy to add metadata to my code to support such a system. The only aspect of your proposal that I am not happy about is this: > 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 Since the standard docstring in :doc is required for Clojure's built- in doc and find-doc, your proposal amounts to having a copy of the docstring with wiki formatting added in :wiki-doc. I don't like the idea of duplicating the docstring for several reasons: - sooner or later :doc and :wiki-doc will differ because an update is applied to only one of them - it implies extra work for every single documented function - it makes the code harder to read, all the more because there is no syntax support for :wiki-doc. I would prefer to have a single docstring containing optional markup. There are (at least) two possibilities: 1) Use a very lightweight markup that preserves readability even without any processing. 2) Add a markup stripper/transformer to Clojure's doc and find-doc functions. > 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. That's a nice feature. Konrad. --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
