Christopher Petrilli <petri...@amber.org> writes: > Interestingly, the Python community does something like this. Usually > there's a very brief explanation of the function/class, a blank line, > then more, and many tools take this into account. Seems like it might > be a good way to split it up. >
Similarly, in Emacs (elisp) documentation the first line (i.e. ending on the first newline) is meant to be a single self-contained sentence describing the function. Many tools/functions use only this first line. Another elisp convention that may be worth adopting is the use of quotes, specifically `' to delimit variable and function names in documentation. These then look nice in plain text documentation, but also allow the documentation engine to turn them into links in those formats that support documentation links. It's a nice low-overhead way to add links to documentation without having to worry that every time you use the word "and" in a sentence it will link to the and macro. Best -- Eric > > Chris > > On Wed, Oct 27, 2010 at 1:09 PM, Ryan Waters <ryan.or...@gmail.com> wrote: >> What if documentation came in two (embedded?) forms, e.g. >> >> (doc ...) >> (doc-verbose ...) >> >> One could be a terse version of the documentation using docstrings >> (doc) and the other could have the bells, whistles, etc. to be shipped >> with the code in an as yet undetermined manner (as posited by this >> post ; ) >> >> - Ryan >> >> >> On Tue, Oct 26, 2010 at 12:08 PM, Tom Faulhaber <tomfaulha...@gmail.com> >> wrote: >>> Nah, changing the autodoc generation is easy (though we need to figure >>> out where images go on the input and output sides and move them >>> around, but that shouldn't be too much of a problem). >>> >>> The bigger problem is figuring out what to tell folks who type (doc >>> foo) at the REPL and get a bunch of gobbledegook back. That's the >>> thing that's been making me look for a better format than markdown. >>> (Autodoc already does markdown translation for supporting >>> documentation). >>> >>> Tom >>> >>> On Oct 26, 9:25 am, Andrew Gwozdziewycz <apg...@gmail.com> wrote: >>>> On Tue, Oct 26, 2010 at 12:21 PM, Eric Schulte <schulte.e...@gmail.com> >>>> wrote: >>>> > Chris <christopher.ma...@gmail.com> writes: >>>> >>>> >> On Oct 26, 9:54 am, Andrew Gwozdziewycz <apg...@gmail.com> wrote: >>>> >>> I like that idea, especially if it could be extended to reference >>>> >>> other code: >>>> >>>> >> Agreed. So now that's links to images, web pages, Clojure vars... >>>> >> anything else? >>>> >>>> > LaTeX equations. Which are increasingly easy to render in HTML >>>> > (e.g.http://www.mathjax.org/). >>>> >>>> I guess the problem is actually making a patch to autodoc to do this all :) >>>> >>>> > -- >>>> > 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 >>>> >>>> --http://www.apgwoz.com >>> >>> -- >>> 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 >> > > > > -- > | Chris Petrilli > | petri...@amber.org -- 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
