The literate programming discussion centered around the question "what should be the state of the art in clojure documentation", not "what is the state of the art in clojure documentation".
If you're looking for API documentation then literate programming is the wrong tool. An API would document calling conventions and something like javadoc would be most appropriate. For the API see http://clojuredocs.org/quickref/Clojure%20Core A literate program is intended as a novel-like presentation where the code is presented along with its motivation. So you would expect to find a discussion of why 32-way trie-like structures are used in data structures or why data structures are immutable. This information is available in some videos but has not been associated with the code. Tim Daly Mark Engelberg wrote:
I spent some time recently documenting a large clojure project. The approach I used was a combination of doc-strings, comments throughout my code, and a project-wide emacs-org-mode file summarizing the point of each file, the important functions in each file categorized by purpose, and an overview of how to use those functions effectively. It worked, but I'm not entirely pleased with the result. There was a lot of duplication between the org-mode file and the comments within the files, and I have a feeling it will be hard to maintain the documentation as the project evolves. autodoc doesn't work on Windows, but even if it does, I'm not certain it would be sufficient for me. As far as I know, it's main purpose is to show an alphabetized API of all the public functions and docstrings, which is a good start, but doesn't allow for the kind of categorization and usage notes I think would be ideal. A couple years ago, when I was doing a lot of Actionscript coding, I fell in love with Natural Docs (http://www.naturaldocs.org/) and this is really the kind of thing I would most enjoy using if I'm going the route of automatically extracting comments and doc strings, because it gives good control over how the API is organized, and the extra annotations are quite readable in the code. The recent post of the website that displays the clojure API categorized by purpose is a good example of the kind of thing I'm looking for. Recently, there was a thread about Literate Programming, including org-babel and Mark Fredrickson's changeling lein plugin, which also raised interesting possibilities. So I'm guessing a lot of people are interested in versatile doc tools and are working on and exploring the options. So this seems like a good time to ask: what is the current state-of-the-art in Clojure documentation tools?
-- 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 Note that posts from new members are moderated - please be patient with your first post. 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
