Hacker News Reader

Hacker News

Comment by RyanMcGreal | Hacker News Reader

Parent Full thread

RyanMcGreal

Python's got excellent documentation, both official and third party.

View on HN

Python itself does, but the third party modules (which do most of the heavy lifting) generally don't. See: Twisted.

Third party documentation doesn't count in this discussion.

It does when one of the big criticisms of PHP is that it rolls everything into core that'd normally be third-party.

Considering how PHP doesn't have anything like Twisted (and this is just one example out of many) ; no, it doesn't count.

Also, I never used a popular Python library for which I haven't found good resources.

My favorite Python library, called NLTK, which has no equivalent in PHP or Ruby or any other platform for that matter, comes with a freaking book that's available for free.

Twisted has semi-decent documentation, see

http://twistedmatrix.com/documents/current/api/twisted.html

http://twistedmatrix.com/documents/current/core/howto/index....

http://twistedmatrix.com/trac/wiki/Documentation

It's not as comprehensive and shiny as the core Python docs, but along with the tutorials and examples, it's actually pretty decent.

Perl is a good example where most third-party modules have good documentation. Or at least a SYNOPSIS you can poke, some DESCRIPTION of what the module does, and a few hundred lines of code in the t/ directory that test all the features of the modules.

The one thing I miss in Python is the inability to click "view source" in my web browser to see how a core Python library is implemented. PHP also has this problem. (Code is the best documentation. Learn to read it.)

If you're talking about the search.cpan.org links to source, I'm right there with you.

The only thing I wish they had was a way to pipe it through a highlighter like perltidy with html out. That'd probably just lead to holy wars on formatting/colours though.

MetaCPAN (http://metacpan.org) has a pretty source view.

For eg. https://metacpan.org/source/DRAEGTUN/Builder-0.05/lib/Builde...

Awesome. search aliases duly updated.

There's high variation in quality amongst third-party modules, but the "modern" python community takes documentation quite seriously, there's even a complete site dedicated to nothing but hosting compiled documentation[0]. Projects like Django, Flask, SQLAlchemy or Flask have rather good documentation sets.

[0] http://rtfd.org

Oh! Well, I must've missed that train (haven't done py for a few years). A couple of years ago, you had to get your info from a mix of a tutorial and a library reference, and most functions were documented with 3-4 sentences max and no examples.

Hmm, that said, that's still exactly what I find on the official Python site (e.g. http://docs.python.org/library/stdtypes.html#string-methods - PHP beats this by lightyears with a single page with examples and comments per function). Which 3rd party thing should I be looking for? (genuinely interested btw - the docs is one thing i dislike about python, and maybe unrightfully so, apparently)

> e.g. http://docs.python.org/library/stdtypes.html#string-methods - PHP beats this by lightyears with a single page with examples and comments per function

1. Please explain why you need more explanation of these very basic functions

2. PHP's doc comments are unadulterated garbage

3. When things are worth documenting, they are: http://docs.python.org/py3k/library/collections.html

4. if you truly think string methods are insufficiently documented, it is very easy to contribute to the documentation.

Maybe you're looking more for a tutorial, and not a reference? I've always found the online Python docs excellent, and provided me with exactly the information I need.

Frankly, no. Just no.

The REASON PHP needs a page per function is the sheer number of poorly handled edge cases, version incompatibilities, and gotchas.

Reply on news.ycombinator.com