Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

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

Closed
zk opened this Issue Oct 23, 2010 · 9 comments

Comments

Projects
None yet
2 participants
Owner

zk commented Oct 23, 2010

Suggested by Christopher Maier and Dennis Crenshaw at the conj.

Owner

zk commented Oct 25, 2010

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}")
  • 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....

Owner

zk commented Oct 28, 2010

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:

  • 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.

Owner

zk commented Oct 29, 2010

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.

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.

Owner

zk commented Nov 6, 2010

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 Nov 27, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment