On Wednesday, September 21, 2016 at 1:10:37 PM UTC-4, John Gabriele wrote: > > On Wednesday, September 21, 2016 at 9:54:23 AM UTC-4, Eli Naeher wrote: >> >> On Wed, Sep 21, 2016, at 06:36 AM, nare...@helpshift.com wrote: >> >> Is there a convention to be followed for referring the parameters of a >> function in the docstring, e.g. for emacs lisp we upcase the parameter name? >> >> >> Uppercase is (or was) also pretty standard style in Common Lisp. In >> Clojure there does not seem to be a standard. Bozhidar Batsov's Clojure >> Style guide is silent on this. Core Clojure docstrings do not seem to >> identify parameters in docstrings with any special style. Some people use >> Markdown-style backticks, but I'm not sure how widespread that usage is. >> >> -Eli >> > > > I believe the Style Guide only codifies established styles, and I don't > think there is one for this. > > I'd use a Pandoc-markdown definition list in your docstring. For example, > for `(defn foo [num to from] ...)`: > > ~~~ > `num` > : the number of frobnicators > > `to` > : location it's going to > > `from` > : location it's coming from > ~~~ > > I don't know if the markdown processor for codex supports this markup, but > I think it's good and it's used by a few other markdowns besides Pandoc. > > -- John > >
Forgot to add that that's the markdown syntax for definition lists (the backticks are just to format the definition terms in monospace). And it degrades pretty nicely for any md processors that don't support that syntax. -- 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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
