Suggested by Christopher Maier and Dennis Crenshaw at the conj.
More to come....
This is awesome. I think it's more than enough to seed with, so I'll be working on putting the finishing touches today (email notifications, mostly). Feel free to keep adding here till we can get this live.
Here's another I just found:
Also, "almost always preferable" indicates that there may be some situations where memfn is appropriate, but there's no indication of what those may be.
Good stuff, I would think mentioning that #(.someMethod %) is more idiomatic than memfn would be helpful to mention. I've been trying (by reading other docstrings) to gauge how 'good' it would be to put see-alsos directly into the docstrings, and it seems like this is done in several places, such as: contains?, extend, and replace.
This would also apply to some of the docstrings you mentioned earlier.
All-in-all it's great we're having this discussion, it helps to validate this feature in my mind.
Zack, you might want to check out this recent thread on the mailing list. It started with me asking if Autodoc could handle embedding images into docstrings, but kind of evolved into a discussion about how best to extend Autodoc to make really rich documentation.
Interesting stuff, I'd be interested in integrating any changes into the way clojuredocs works, automatically parsing display info, examples, see-alsos, etc.
I've been on a major yak-shave on docstring comments lately due to email notifications. I'm finally through most of it and making forward progress again.