I'd like to announce the availability of CJD 0.1.0.
CJD is a technology for documenting Clojure programs which I devised to satisfy my idiosyncratic documentation-related propensities. It's mostly complete, so I thought I'd share it with the community just in case there are any fellow travelers with similar inclinations. CJD makes use of structured comments embedded in Clojure source code in a fashion inspired by Javadoc, to which it bears a superficial similarity. Like Javadoc, CJD comments support a simple form of markup that not only can add formatting detail but also provides a modicum of metadata that describes what's being documented. This allows CJD's processing facility to extract the documentation content from collections of Clojure namespaces and convert it into trees of consistently-formatted HTML documents. Thus, CJD comments represent a much more expressive alternative or supplement to docstrings. Ground zero for CJD is its home on GitHub <https://github.com/greenh/CJD>, which includes a FAQ <http://greenh.github.com/CJD/doc/FAQ.html> that provides a reasonably concise overview and rationale for CJD, and a user's guide <http://greenh.github.com/CJD/doc/User.html> that represents a first-pass attempt at describing the gory details. Needless to say, CJD uses CJD for its own program documentation. You can see the output of a representative namespace in your choice of light-background <http://greenh.github.com/CJD/doc/light/cjd.exome.html>and dark-background <http://greenh.github.com/CJD/doc/dark/cjd.exome.html> (my favorite!) renderings, and the source from which it was generated here<https://github.com/greenh/CJD/blob/master/src/clojure/cjd/exome.clj> . Here's a few additional points about CJD. You'll get all these and more from the links above, but just in case your interest hasn't already been piqued… - Documentation comments generally consist largely of ordinary text, so they're easily readable in source form. Required additions for markup and escape sequences tend to be fairly minimal. - Markup is structured in terms of syntactically valid Clojure forms, allowing Clojure-aware editors to be used to good advantage. - A recursively-defined documentation syntax allows Clojure's recursively-defined data structures and functions to be documented to whatever depth is needful. - Structure-aware support for documenting core Clojure artifacts (vars, functions, macros, protocols, records, etc.) is available right out of the box. CJD also provides facilities for extensions that allow user-defined artifacts to be compatibly documented. - Recognizing the value of richly-linked documentation, CJD tries to make it easy to link to other artifacts' documentation, both within and external to a project. - What does and doesn't get documented, and to what extent, is entirely at the developer's discretion. No pressure, no complaints—CJD happily accepts whatever scraps of documentation you throw its way. And, it's available from Clojars <https://clojars.org/cjd>, it includes a plugin that works with both the 1.x and 2.x versions Leiningen, it runs from the REPL, and there's even support for all you command-line enthusiasts out there. Enjoy! --- Howard -- 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
