Hacker News new | comments | show | ask | jobs | submit login

> Did you ever read Python's documentation?

Yes. it's rather fucking good.

> Show me one popular web programming language which has a full page, up to date, with examples and user comments and version incompatibility info, per function.

Have you ever read Python's documentation? In the last ten years?

Python's docs have a complete and readable description of the language[0] including its data model and the various core protocols[1], it has a number of quality howtos and guides[2] a complete documentation of how to use C-level APIs[3][4], a pretty good and complete tutorial for beginners[5], a complete, well written and exhaustive changelog with examples[6] drilling down to C API changes[7] and most stdlib modules are extensively documented with examples and links to to the actual source code for the module[8] and versioning information[9], with the whole documentation being heavily hyperlinked and permalinked (every section, subsectio, sub-sub-section, class, method, function or constant getting its very own anchor) linking to its own source[10]. And just in case you want to contribute, or even just want the documentation offline, it's included in the source tree and trivially compiled to not only an HTML version, but a PDF (via latex), plain text or EPUB one as well[11]. Hell, the documentation is so extensive there's even documentation on documenting[12].

Oh, and the documentation is available for every single version of Python past, present or future (for which it could be found anyway, as far as older versions of the language are concerned), including bugfix releases[13]. And then it goes the extra mile by letting you run examples to ensure nobody broke them[14].

As to "full page per function", I really don't think you need that. And the PHP doc comments are closer to youtube comments than to anything worth reading, I simply can not see them as anything but liabilities.

[0] http://docs.python.org/py3k/reference/index.html

[1] http://docs.python.org/py3k/reference/datamodel.html

[2] http://docs.python.org/py3k/howto/index.html

[3] http://docs.python.org/py3k/c-api/index.html

[4] http://docs.python.org/py3k/extending/index.html

[5] http://docs.python.org/py3k/tutorial/index.html

[6] http://docs.python.org/py3k/whatsnew/3.2.html

[7] http://docs.python.org/py3k/whatsnew/3.2.html#build-and-c-ap...

[8] http://docs.python.org/py3k/library/collections.html]

[9] http://docs.python.org/py3k/library/collections.html#collect...

[10] http://docs.python.org/py3k/_sources/library/heapq.txt

[11] http://hg.python.org/cpython-fullhistory/file/tip/Doc

[12] http://docs.python.org/documenting/index.html

[13] http://www.python.org/doc/versions/

[14] http://sphinx.pocoo.org/ext/doctest.html

(the lack of markup in HN comments is getting seriously annoying)

Don't forget being able to do this from within the interpreter:

    >>> print abs.__doc__
    abs(number) -> number

    Return the absolute value of the argument.
    >>> print xrange.__doc__
    xrange([start,] stop[, step]) -> xrange object

    Like range(), but instead of returning a list, returns an object that
    generates the numbers in the range on demand.  For looping, this is 
    slightly faster than range() and more memory efficient.

True, or from your OS's shell:

    > pydoc unittest
    Help on module unittest:




        Python unit testing framework, based on Erich Gamma's JUnit and Kent Beck's
        Smalltalk testing framework.
        This module contains the core framework classes that form the basis of
        specific test cases and suites (TestCase, TestSuite etc.), and also a
        text-based utility class for running the tests and reporting the results

Or from ipython, even better:

    In [1]: abs?
    Type:		builtin_function_or_method
    Base Class:	<type 'builtin_function_or_method'>
    String Form:	<built-in function abs>
    Namespace:	Python builtin
       abs(number) -> number
    Return the absolute value of the argument.


    In [1]: import json
    In [2]: json.dumps??
    Type:       function
    Base Class: <type 'function'>
    String Form:<function dumps at 0x101f0bc08>
    Namespace:  Interactive
    File:       /usr/local/Cellar/python/2.7.2/lib/python2.7/json/__init__.py
    Definition: json.dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, encoding='utf-8', default=None, **kw)
    def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
            allow_nan=True, cls=None, indent=None, separators=None,
            encoding='utf-8', default=None, **kw):
        """ [snip (excellent) docstring] """
        # cached encoder
        if (not skipkeys and ensure_ascii and
            check_circular and allow_nan and
            cls is None and indent is None and separators is None and
            encoding == 'utf-8' and default is None and not kw):
            return _default_encoder.encode(obj)
    #snip rest of func

I usually use the help function, instead of reading __docs__ directly.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact