How a programming language documentation ought to look like: clojuredocs | Hacker News Reader

How a programming language documentation ought to look like: clojuredocs

clojuredocs.org

83 pointsalbertcardona34 comments

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

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.

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.

That needs more explaination.

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

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.

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

I have used ipython. How do you easily reload arbitrarily nested modules? How do you easily redefine only one function in some module and have that change be reflected globally?

What has that got to do with introspection?

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

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.

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

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.

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

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

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.

Io's layout is still my favorite:

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

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.

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

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

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

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.

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/

Trying to select the code includes the line numbers.

s/How a/What/

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

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.

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.

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

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.

The classic example of where this actually works well is in the PHP docs. Yes, you get idiots, but you also get good, real-world examples of a wider variety than the original documentation authors would have been able to produce. It's about the only thing I missed when I jumped from PHP to Python.

I think the Django Book's approach to this is really good as well, where the moderator overhead is implicitly taken on by the documentation authors. That works for them because they treat the document as a project in itself, rather than as a by-product.

Your bug is my feature.

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.

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

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

Reply on news.ycombinator.com