I have found long docs like that to be useful in some major top-level function if it has a large sort of input and configuration parameters to pass in.
Markdown I believe means with back ticks around the symbol to make it stand out as an actual art name vs some other word in the sentence. I have seen this be a popular doc style in lisps that I've looked at. When case insensitive I've seen all caps used, which would not work in Clojures case. I've like the back tick markdown style since it doesn't get as easily confused with something like quote. I've also tended to use markdown ticks around code expressions of they were used in the doc string. I'm not sure I've seen a lot of that in the wild though. Doing that on every(most) function I'd be worried would be a maintenance issue. I've wrote doc string style where the arguments are enumerated in an obvious argument name -> description way. It definitely makes it unambiguous. I still tend to reserve that for "larger", more complex functions. While in simpler functions just ensuring all args referenced directly and markdown ticked and are described in a natural type of sentence/paragraph. The idea of consistently naming arguments/types of arguments a certain way is obviously nice too -- 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.
