On Tuesday, May 6, 2014 1:41:25 PM UTC-4, puzzler wrote: > > On Tue, May 6, 2014 at 9:56 AM, Sean Corfield <se...@corfield.org<javascript:> > > wrote: > >> >> > Sean, I think you missed the point of that example. The point was that > the docstring actually makes sense if it were written as: > > Returns a new seq where `x` is the first element and `seq` is the rest. > > Note how using standard markdown syntax helps distinguish the reference to > the `seq` arg and the more generic use of the term seq. > > I think the Clojure community's lack of meaningful support for markdown in > docstrings is a glaring weakness that is fairly easy to rectify. In the > meantime, I've begun using markdown syntax in my own docstrings, figuring > that someday the tools will eventually catch up and support it. > > Using markdown in docstrings would be fantastic. This would enable tools like codox and autodoc to produce nice-looking html output from docstrings, instead of just <pre>docstring here</pre> output.
And the difference between the current Clojure docstrings and updated markdown-formatted docstrings is pretty minimal. Heck, I bet that markdown-i-fying the docstrings would even provide an easy on-ramp for a lot of folks (myself included) to get involved in the patch submission process... Incidentally, I see that the [Rust](http://www.rust-lang.org/) folks use markdown-formatted docstrings. Have a look at some of [their API docs](http://static.rust-lang.org/doc/master/std/index.html). Very nice. -- 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.
