Re: [ANN] CJD 0.1.0, a documentation technology for Clojure programs
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.comjavascript: 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
[ANN] CJD 0.1.0, a documentation technology for Clojure programs
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.htmland dark-background http://greenh.github.com/CJD/doc/dark/cjd.exome.html (my favorite!) renderings, and the source from which it was generated herehttps://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
Re: [ANN] CJD 0.1.0, a documentation technology for Clojure programs
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.htmland 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
Re: [ANN] CJD 0.1.0, a documentation technology for Clojure programs
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 hhgr...@ieee.org 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 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
