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.

Reply via email to