Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Add docstring discussion mechanism to flag confusing / incorrect docstrings and track suggestions. #21

Closed
zk opened this Issue · 9 comments

2 participants

@zk
Owner
zk commented

Suggested by Christopher Maier and Dennis Crenshaw at the conj.

@zk
Owner
zk commented

Seed content:

  • cond - mention :else idiom?
  • loop
  • ns-map - Kind of short, maybe mention something about return map characteristics ("returns a map where keys are symbols and values are the vars those symbols name, i.e. {map #'clojure.core/map}")
@christophermaier
  • if-let - this has to be one of the more cryptic doc strings in the entire language
  • comment - talk more about the implications of using this to comment out code; early on, I got bitten by this when I naively commented out the final form of a function (thus making the function unconditionally return nil). Contrast with the #_ reader macro for completeness.
  • contains? - explicitly bring out the fact that if you want to test for the presence of a value as opposed to a key / index, you should use clojure.core/some (it's mentioned, but without giving a reason). Also really drive home that contains? only operates on keys, as this is a common stumbling block for newbies.
  • conj - give examples of how conj behaves with different data structures (add at beginning of lists, end of vectors, adds a 2-element vector for maps, etc.)
  • concat / lazy-cat - after reading the docs for both of these, I'm not clear on the difference between them
  • create-struct - incredibly terse and vague; should also mention that now you probably want to use defrecord instead.
  • eval - mentions that this works on data, not text, but doesn't tell you what to use if you need to evaluate text! (probably load-string)
  • for - better explain how to use the :let, :when, and :while keys
  • extends? / satisfies? - what's the difference between these two?

More to come....

@zk
Owner
zk commented

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.

@christophermaier

Here's another I just found:

  • memfn - According to the Clojure / Java Interop page, it is "almost always preferable" to use an anonymous function instead of memfn. I also found a comment by Stuart Halloway here (scroll down near the bottom; no direct links, sorry) that says "memfn is a living fossil". The doc for memfn doesn't have any of this, however.

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.

@zk
Owner
zk commented

Chris-

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.

@christophermaier

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.

@zk
Owner
zk commented

Chris-

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.

@zk zk closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.