3 ms·

I think the docs have a lot to gain. If you take a look at https://clojuredocs.org/clojure.core/reify https://clojuredocs.org/clojure.core/reify as an example,

by bpicolo 10y ago

I think the docs have a lot to gain. If you take a look at https://clojuredocs.org/clojure.core/reify https://clojuredocs.org/clojure.core/reify as an example, it's pretty much impossible to figure out what the heck reify does by reading that page. That's not universally the case, but definitely a frustration. The examples are frequently the only way I can begin to figure out the usage of something at all (and they're typically the simplest-case example). I love examples in general, but it still speaks to the difficulty of parsing through some of those function documentations.

nilved 10y ago
https://www.conj.io/store/v1/org.clojure/clojure/1.8.0/clj/clojure.core/reify https://www.conj.io/store/v1/org.clojure/clojure/1.8.0/clj/c... clojuredocs.org is just one community-powered docs site; there are several.
- bpicolo 10y ago
  And that site has the exact same code-generated documentation, just with some different CSS. They just parse the clojure source. https://github.com/clojure/clojure/blob/f572a60262852af68cdb561784a517143a5847cf/src/clj/clojure/core_deftype.clj#L71 https://github.com/clojure/clojure/blob/f572a60262852af68cdb...
  - yogthos 10y ago
    ClojureDocs isn't just generated documentation, but provides usage examples. Here's the page for reify https://clojuredocs.org/clojure.core/reify https://clojuredocs.org/clojure.core/reify that illustrates the usage.
    - bpicolo 10y ago
      Yeah, that's the original page I linked, see my first comment. : )
projectileboy 10y ago
In the past I would have agreed strongly, but I have to say that in the last few weeks I've been diving back into Clojure, and the docs at clojure.org are much better than they once were. I like the structure of the "reference" sections, each of which dives into a single concept (e.g., multimethods). I agree, however, that the Getting Started guide is still very thin, and I dislike that the Clojure community seems to want very badly to make you learn emacs before you learn Clojure.

by bpicolo 10y ago

nilved 10y ago

https://www.conj.io/store/v1/org.clojure/clojure/1.8.0/clj/clojure.core/reify https://www.conj.io/store/v1/org.clojure/clojure/1.8.0/clj/c... clojuredocs.org is just one community-powered docs site; there are several.

bpicolo 10y ago
And that site has the exact same code-generated documentation, just with some different CSS. They just parse the clojure source. https://github.com/clojure/clojure/blob/f572a60262852af68cdb561784a517143a5847cf/src/clj/clojure/core_deftype.clj#L71 https://github.com/clojure/clojure/blob/f572a60262852af68cdb...
- yogthos 10y ago
  ClojureDocs isn't just generated documentation, but provides usage examples. Here's the page for reify https://clojuredocs.org/clojure.core/reify https://clojuredocs.org/clojure.core/reify that illustrates the usage.
  - bpicolo 10y ago
    Yeah, that's the original page I linked, see my first comment. : )

projectileboy 10y ago

In the past I would have agreed strongly, but I have to say that in the last few weeks I've been diving back into Clojure, and the docs at clojure.org are much better than they once were. I like the structure of the "reference" sections, each of which dives into a single concept (e.g., multimethods). I agree, however, that the Getting Started guide is still very thin, and I dislike that the Clojure community seems to want very badly to make you learn emacs before you learn Clojure.