Yes, no argument, this is a problem, and I'm open to suggestions for solving it.
As an aside, I personally don't find it to be a problem, as pretty much all of my documentation needs tend to be fulfilled by browser-based mechanisms, and my use of docstrings in a running system is negligible. That notwithstanding, I'm entirely sensitive to the fact that not everyone does it my way... so the notion of tying it into the existing state of affairs is entirely reasonable. Anyway, I'm thinking about it... -- Howard On Tuesday, December 18, 2012 2:47:59 PM UTC-8, FrankS wrote: > > It sure looks very nice! > > … but doesn't your use of #_ preclude us from getting that doc-info in the > running system? > > In other words, how would you enhance the doc facility in the repl to > pickup your doc-meta-data in real-time? > > -FrankS. > > > On Dec 18, 2012, at 11:10 PM, greenh <hhg...@ieee.org <javascript:>> > wrote: > > > 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, which includes a FAQ that > provides a reasonably concise overview and rationale for CJD, and a user's > guide 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 and dark-background (my favorite!) renderings, and the > source from which it was generated here. > > > > 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, 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 clo...@googlegroups.com<javascript:> > > Note that posts from new members are moderated - please be patient with > your first post. > > To unsubscribe from this group, send email to > > clojure+u...@googlegroups.com <javascript:> > > 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
