Awesome! 2012/12/18 greenh <hhgr...@ieee.org>
> 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 -- 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
