On Wednesday, July 25, 2012 8:16:52 AM UTC-4, Tassilo Horn wrote: > > Laurent PETIT writes: > > >> -Is there a way write the docs in a separate place (different section > >> of the document or different document altogether)? > > Sure. > > --8<---------------cut here---------------start------------->8--- > (defn plus1 [x] (+ x 1)) > (alter-meta! #'plus1 assoc :doc "Adds one to x.") > --8<---------------cut here---------------end--------------->8--- >
Wow, that's nice... Reminds me of the paths that Python and Perl have taken regarding this issue. Python goes with having very short docstrings, but then longer separate documentation available elsewhere. I'm personally not crazy about this approach, because I usually end up wanting to know more than the rather skimpy docstrings tell me. Perl 5 doesn't have docstrings, but they do have an embedded "POD" markup doc format, the content of which often serves as docstrings (though POD is also used for longer external docs as well). I'm much happier with the richer Perl 5 docs, but the issue of having all those docs clog up your code had led to a best practice of just moving them all to the end of the file. Tassilo's note that you can use `alter-meta!` for roughly the same thing seems similar to the Perl 5 approach giving you the best of both worlds: * you end up with more complete docstrings (making your users happier), * that don't clog up your code (or require code-folding to achieve that end), and * that still go in the same source file (thus keeping your code and api docs together). I'd imagine that it wouldn't be too difficult to create a tool to extract docstrings out into alter-metas at the bottom, or the reverse --- gather up alter-metas at the bottom and stitch them into their respective function defns, if that's your preference. I like it. Make your docstrings as long as they need to be (perhaps add some examples?). Even format them in markdown to make them more readable in the repl. ---John -- 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
