Did you ever read Python's documentation? Or Ruby's? Or Java's?
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.
Of course, it's just one point and I otherwise agree with your comment, but it's one hell of an advantage.
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)
>>> 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. > pydoc unittest
Help on module unittest:
NAME
unittest
FILE
/System/Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/unittest.py
MODULE DOCS
http://docs.python.org/library/unittest
DESCRIPTION
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
(TextTestRunner).
[snip] In [1]: abs?
Type: builtin_function_or_method
Base Class: <type 'builtin_function_or_method'>
String Form: <built-in function abs>
Namespace: Python builtin
Docstring:
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)
Source:
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 funcHa-ha-ha. You're kidding, right?
Check strlen: http://www.php.net/manual/en/function.strlen.php
Comments:
1. Comment about how PHP converts types. "Conclusion: The values are converted to string before check the lenght."
2. Comment from a novice user who posted a solution to the problem of subtracting the number of spaces in string from its length.
3. Comment about someone who thought that there was a bug in strlen, but it actually was a documented difference in behavior between two minor versions of PHP.
4. Comment about counting characters in UTF-8 encoded string by decoding it to some other one-byte encoding.
5. Comment about counting characters in UTF-8. Actually, the whole new function.
6. Reminder that \r\n are actually two bytes! "If I had thought of this starting out, I would have saved myself several hours of trouble trying to get php to cut a message to the same length that my auxiliary javascript validation imposed on it."
7. Benchmarks for different UTF-8 strlen implementations.
8. Complaint about another comment, which suggested the function to count characters in UTF-8 strings that didn't work. And the "proper" solution using regular expressions.
...
I can't speak for Ruby or Java because I haven't even looked at their documentation sites.
User comments? PHP user comments are crap, IMHO - so many people writing so much horrible code in those comments.
I understand where a lot of PHP supporters are coming from because I was once there - I spent four years with the language and thought it was the most beautiful thing that existed. Until Python, Scheme, Erlang, and Haskell invaded my life.
PHP will always be an amateur programming language - which is it's strength, kind of like BASIC, a great stepping stone but nothing more.
1. Python doc has full up to date documentation for everything shipped with the standard library (which dwarfs PHPs grab bag of globally scoped functions)
2. The comments in PHP documentation are frequently out of date, misleading, or flat out wrong. Among the people I work with (who are working on PHP web apps, full time) everybody routinely advises the PHP noobs to ignore the comments.
3. The standard library functions shipped with most languages don't require a full page with multiple examples to explain how they work.
Don't get me wrong, the documentation for PHP is excellent, but it's a small win for a language that has so many real --language level-- issues.
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.
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.
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.)
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.
For eg. https://metacpan.org/source/DRAEGTUN/Builder-0.05/lib/Builde...
[0] http://rtfd.org
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)
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.
The REASON PHP needs a page per function is the sheer number of poorly handled edge cases, version incompatibilities, and gotchas.
For example: http://msdn.microsoft.com/en-us/library/w4hkze5k.aspx
or
http://msdn.microsoft.com/en-us/library/system.object.member...
You get the syntax (including VB, C++, and F# where availalbe), remarks, examples, version information, platforms, comments, and related content.
I mean, just look at that first URL!