How a programming language documentation ought to look like: clojuredocs

http://clojuredocs.org/clojure_core/clojure.core/defn

by albertcardona • 16 years ago

83 34 16 years ago

clojuredocs.org

fisadev• 16 years ago

That needs more explaination.

This is a better example, I think: http://docs.python.org/library/csv.html

swannodette3• 16 years ago

I'm just glad that Clojure has a good community driven documentation site that's approachable for newcomers. As far Python documentation goes I've never considered it particularly useful.

For me, the best kind of documentation is self-documentation. I love dir and the various forms of introspection at the Python interpreter. However, the Clojure REPL story, being a Lisp, just makes the Python interactive introspection experience look pathetic.

The thing about interactive documentation is that I, at least, find it much more likely that I'll remember it. When I just read something it tends to be forgotten shortly thereafter.

bretthoerner• 16 years ago

> However, the Clojure REPL story, being a Lisp, just makes the Python interactive introspection experience look pathetic.

Have you ever used ipython? Can you give an example of how it pales in comparison? Typing dir() or help() sounds awful, I hope no full-time Python developers do that.

    import csv
    csv.<tab>

Blammo, tab completed dir().

    csv.reader?

Blammo, docstring, method signature, and more.

    csv.reader??

Blammo, code for the method.

Wilfred• 16 years ago

Python's docs are reasonable, but could be better. I don't like the left-hand contents, I find it breaks the flow. Wikipedia's inline contents seem far more intuitive. I'd like to be able to jump to specific functions.

(Moving to bpython solved most of these problem though, as it shows the docstring for a given function inline.)

Also, you end up spending a lot of time reading the docs and so a little typographical polish wouldn't hurt. The page is simply too wide.

joe_the_user• 16 years ago

It seems like an example of how automatic documentation generation spews out garbage unless you work to create comments specifically for documentation.

honza• 16 years ago

I disagree. It doesn't look very well-organized. Python's docs are much cleaner.

regularfry3• 16 years ago

Python's docs lack a place for comments, which is a shame.

forsaken• 16 years ago

Your bug is my feature.

codefisher• 16 years ago

It would just turn into a place where nobs ask questions, and you really want that done in the proper place. And you also have the moderator overhead.

jimmyjazz14• 16 years ago

I feel like pythons docs are hard to use, its difficult to just look up a method quickly also the search feature never seems to be very accurate for me. I will give the python docs credit when it comes to supplying good examples though.

falcolas• 16 years ago

Once I figured out where to find the built-in functions, I haven't had a problem finding things since.

Docs > Library Reference > Built-In Functions (browser search for function)

I appreciate that they include all of the built-in functions in the same root directory as the remaining batteries-included modules.

The only wonky one for me now is the documentation for formatting strings, since it's documented in the "strings" module, but it's not dependent on the strings module.

torme• 16 years ago

I agree that the examples are nice, but it'd also be awesome if there was some explanation as to what that function did.

dpritchett• 16 years ago

To be fair that's the official docstring for defn. When you browse over to the docs for def (http://clojuredocs.org/clojure_core/clojure.core/def) the official docstring tells you to go look it up on clojure.org:

    Please see http://clojure.org/special_forms#def

I believe this odd behavior is because Clojure's special forms are written in java and thus don't have easily parsed .clj source for the automatic clojure doc search tools.

sz• 16 years ago

Io's layout is still my favorite:

http://www.iolanguage.com/scm/io/docs/reference/

jedbrown• 16 years ago

Hoogle is pretty cool: http://haskell.org/hoogle/?hoogle=m+a+-%3E+(a+-%3E+b)+-%3E+m...

pjscott• 16 years ago

The thing I love about Haskell's documentation is that it usually includes the full highlighted source code, all nicely linked. That's tremendously useful when you're diving into new code.

smackfu• 16 years ago

My favorite is the perl ones, which have tons of very useful comments giving examples.

protomyth• 16 years ago

I am starting to wish for ePub versions of the docs. That would let us use our eReaders/iPads.

gregwebs• 16 years ago

Just released for ruby. http://tenderlovemaking.com/2010/04/12/rdoc-on-your-ipad/

draegtun• 16 years ago

Ditto for Perl: http://blogs.perl.org/users/olaf_alders/2010/07/icpan-cpan-o...

vito• 16 years ago

Pales in comparison to Scribble, Racket's documentation system. Filled with examples, all interlinked: http://docs.racket-lang.org/reference/define.html

I modeled Anatomy, Atomo's documentation system on it: http://atomo-lang.org/docs/core.html

swannodette3• 16 years ago

ClojureDocs are also interlinked and I think in an even more interesting way - any other vars that appears in the Clojure core source are linked to. A great way to understand how the core of Clojure is interconnected.

Racket's docs are good but it could use more styling. You've done a good job w/ that with Atomo.

albertcardona• 16 years ago

It has a search function.

I has example code and comments. Just like http://php.net did and which gave it enormous popularity and ease of use. What the docs don't explain a comment or an example clear it up.

The clojuredocs author knows the site needs to become even better. I thank him for what the site already delivers.

roder• 16 years ago

My favorite docs are http://erldocs.com/

The speed and ease at which I can search the erlang docs for specific functions is the best I have found.

alexyoung• 16 years ago

s/How a/What/

swah• 16 years ago

Not a great example of content, but the search here is really fast, I'd love something like this for clojure core + contrib: http://ukijs.org/docs/

kylecordes• 16 years ago

ClojureDocs is quite nice. One thing I noticed is that a peek in its source code:

https://github.com/zkim/clojuredocs

shows that it's a Ruby+Rails app. RoR is a good choice for this kind of thing, but it would be slightly slicker if ClojureDocs had Clojure under the hood.

afhof• 16 years ago

Trying to select the code includes the line numbers.

gcb• 16 years ago

i read that page and i'm still clueless as to the need of & in the argument list...

regularfry3• 16 years ago

That's because it's a library reference, not a syntax tutorial.

Now, there's an argument that it should have a syntax reference as well, but that doesn't seem to be the goal (yet).

hbt• 16 years ago

It's good but it could be better.

e.g:

- stack overflow running on top of that to rate comments + index questions asked on functions

- smart snippet indexer. Examples rarely cover everything

- smart way to deal with changes over multiple revisions. Functions are updated and comments are either deprecated or it's a new page.

I think one should work on something like stackoverflow but for documentation. Where you could supply some sort of parser for your specific programming language but have something uniform with all the basics.

How a programming language documentation ought to look like: clojuredocs

Related Stories