News for hackers. Stuff that matters.
Re:How a programming language documentation ought to look li... by fisadev on Friday November 19, 2010 @04:14PM (#1922815)
That needs more explaination.

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

Re:How a programming language documentation ought to look li... by swannodette on Friday November 19, 2010 @05:19PM (#1923044)
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.

Re:How a programming language documentation ought to look li... by bretthoerner on Friday November 19, 2010 @06:57PM (#1923303)
> 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.
Re:How a programming language documentation ought to look li... by swannodette on Friday November 19, 2010 @07:30PM (#1923383)
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?
Re:How a programming language documentation ought to look li... by pig on Friday November 19, 2010 @07:51PM (#1923442)
What has that got to do with introspection?
Re:How a programming language documentation ought to look li... by joe_the_user on Friday November 19, 2010 @07:50PM (#1923437)
It seems like an example of how automatic documentation generation spews out garbage unless you work to create comments specifically for documentation.
Re:How a programming language documentation ought to look li... by Wilfred on Friday November 19, 2010 @06:15PM (#1923224)
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.