See http://en.wikipedia.org/wiki/Axiom_computer_algebra_system
which is "in process" to become a fully literate computer
algebra system. 20 volumes so far and a lot of documentation
still to come.
Once a system gets larger than one person's head (e.g. Rich's)
then the question of "why" becomes interesting. Once it becomes
large enough to have a full community the question of "why"
becomes vital. Unfortunately, the "why" answers rarely get
written down by the primary developers and the follow-on developers
have to guess.
Literate programs are a place to write down what motivates a design
choice (the "why") so that others can share the same motivation.
Thus when they see really complex code (e.g. 32-tries) they can
judge whether this is still reasonable ("should we use 64-tries?")
or whether it should just go away ("the hardware doesn't have cache").
Without the motivation the code will be mangled by well-meaning coders.
The Clojure project needs an english major to become the "editor-in-chief".
This person should not let any code enter the core or the accepted contrib
without a strong story line. Good code, like good characters, should have
strong motivations for what gets done. We should just be able to download
the Clojure "book", read it, and execute it.
Maybe Stu can get his book editor on board :-)
Tim Daly
Joop Kiefte wrote:
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
--
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
