Perhaps you would be interested in postdoc:
http://github.com/markmfredrickson/postdoc
Postdoc allows structured documentation, runnable examples, and
related items based on namespaced identifiers. One was to allow for
separate files that included the documentation away from the code, so
as not to clutter up the source with more information than necessary.
Coders still write short doc strings. Additional information is
included in a separate namespace and is only an (import ...) away.
E.g.
--- foo.clj
(ns foo)
(def add1 "adds one to its argument" [x] (+ 1 x))
(def add2 "adds two to its argument" [x] (add1 (add1 x)))
--- foo/doc.clj
(ns foo.doc
(:use postdoc))
(postdoc add1
:examples ["; (add1 3) => 4\\n(add1 3)"]
:categories [:example-functions :arithmetic]
:references [["Wikipedia Entry" "http://en.wikipedia.org/wiki/
Foo"]
"http://www.example.com";]
:see-also [#'add2])
--------
Right now, the postdoc function stuffs everything into the docstring,
but it would be easy enough to have a global option for that and an
(extended-doc) function to spit out the additional info on request.
I started this project was to make the Incanter docs accessible to
scrapping. It is an example of another large project that is well
documented. The docs are detailed and comprehensive, but contained
entirely in docstrings (usually well structured). I spent some time
moving them over to the postdoc format, but I haven't pushed the
Incanter community to accept the postdoc format.
Here's an example of a real file, documented:
http://github.com/markmfredrickson/incanter/blob/postdoc/modules/incanter-core/src/incanter/doc/core.clj
-Mark
On Sep 7, 3:25 am, Mark Engelberg <mark.engelb...@gmail.com> wrote:
> Docstrings seem designed for fairly terse comments about the nature of
> the function. It's great for providing little hints about how the
> function works to jog one's memory by typing (doc ...) in the REPL, or
> for searching with find-doc. But I just don't think I can fit the
> kind of full documentation I want all into a docstring without ruining
> its REPL usefulness.
>
> My instinct is to put those sorts of things into comments. I think
> adding a huge Clojure metadata map in front of the var would hinder
> code readability. Hmmm, I wonder if maybe there would be a way to use
> a macro to add metadata to the var separate from the function? E.g.,
> (document my-function metadata) That might make the metadata approach
> more palatable...
>
> As a side note, I wish Clojure had some sort of block commenting
> capability. Both (comment ...) and #_ require well formed code to
> follow and sometimes it's just nice to be able to comment out a block
> of text.
--
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
