To have a good idea of how this can work, see Literate Haskell 2010/9/6 Tim Daly <d...@axiom-developer.org>: > 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
-- Linux-user #496644 (http://counter.li.org) - first touch of linux in 2004 Demandoj en aŭ pri Esperanto? Questions about Esperanto? Vragen over Esperanto? Perguntas sobre o Esperanto? - http://demandoj.tk -- 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
