On Nov 2, 1:42 pm, Steven D'Aprano <st...@remove-this- cybersource.com.au> wrote: > It's always difficult to know how much information is too much. The PHP > docs seem to take an "everything including the kitchen sink" approach. > Given that approach, it makes sense to divide everything into > subsections, one page per function. But with Python's minimalist > approach, it would just be annoying. Compare the four lines of: > > http://docs.python.org/library/functions.html#id > > with this re-write in the PHP fashion: > > ===== > id > ===== > (Python 1.x, Python 2.x, Python 3.x) > > id -- id of an object > > Description > ----------- > > id(object) > > id returns the numeric "identity" of an object, which is guaranteed to be > unique and constant for this object during its lifetime. > > Note: two objects with non-overlapping lifetimes may have the same id() > value. > > Note: CPython implementation detail: This is the address of the object. > > Parameters > ---------- > > * object > > Any object. > > Note: all data in Python are objects, even ints and strings. > > Note: there are no undefined objects in Python. If you call > id(variable) on an unbound variable name, Python will raise an > exception. > > Return values > ------------- > > Returns an integer or long integer object representing the ID of the > argument. > > Errors/exceptions > ----------------- > > If the argument to id() is a named variable rather than a literal, and > that name is not bound to any object, then a NameError will be raised. > Otherwise every call to id() must succeed. > > Note: if the call to id() is inside a function, the exception may be a > subclass of NameError such as UnboundLocalError. > > Note: literals are not guaranteed to always refer to the same object. > > Changelog > --------- > > 0.9 First version added (I think). > > Examples > -------- > > id(x) > id(alist[1]) > id(instance.attribute) > id(module.name.attribute['key'].method(arg1, arg2).seq[2]) > > Notes > ----- > > If you're still reading, I admire your persistence. > > See also > -------- > > Python's object model > Exceptions > > Steven
You're right in that the python docs in this case are less lines, but that's one of the problems. It doesn't mention anywhere the extra detail you've added regarding exceptions thrown. That's the kind of thing that probably comes through experience or some kind of convention which isn't obvious to beginners. Having things split into sections - parameters, return types, exceptions, etc - lets me find what I'm looking for quickly. As for the 9 paragraphs statement, there's a usability book that applies here - it's called "Don't make me think". I shouldn't have to go through freeform text to find what I'm looking for when a list would make that information easier to find. And splitting the docs into sections would allow me to skip to what I'm looking for. I really would be much happier with your example documentation. I think the key difference is that I don't want to have to *read* the python docs - I want to be able to scan for what I'm looking for and find it easily. That makes me productive. -- http://mail.python.org/mailman/listinfo/python-list
