[Python-checkins] cpython: Close #4966: revamp the sequence docs in order to better explain the state of

[Nick Coghlan]

On Tue, Aug 21, 2012 at 11:55 AM, Ezio Melotti <ezio.melotti at gmail.com> wrote:
>> +Sequence Types --- :class:`list`, :class:`tuple`, :class:`range`
>> +================================================================
>> +
>
>
> These 3 links in the section title redirect to the functions.html page.  I
> think it would be better if they linked to the appropriate subsection
> instead, and in the case of the subsections (e.g. "Text Sequence Type ---
> str") they shouldn't be links.  The same comment can be applied to other
> titles as well.

I made a start on moving the info out of functions.html and adding
appropriate noindex entries. str, bytes and bytearray haven't been
consolidated at all yet.

>> ++--------------------------+--------------------------------+----------+
>> +| ``s * n, n * s``         | *n* shallow copies of *s*      | (2)(7)   |
>
>
> I would use '``s * n`` or ``n * s``' here.

Done.

>> +| ``s.index(x, [i[, j]])`` | index of the first occurence   | \(8)     |
>
>
> This should be ``s.index(x[, i[, j]])``

Done.

>> +
>> +   * if concatenating :class:`tuple` objects, extend a :class:`list`
>> instead.
>> +
>> +   * for other types, investigate the relevant class documentation
>> +
>
>
> The trailing punctuation of the elements in this list is inconsistent.

Just removed all trailing punctuation from these bullet points for now.

>
> You missed clear() from this list.

The problem was actually index() and count() were missing from the
index for the "common sequence operations" table. Added them there,
and moved that index above the table.

copy() was missing from the index list for the mutable sequence
methods, so I added that.

> Also in the "Result" column the descriptions in prose are OK, but I find
> some of the "same as ..." ones not very readable (or even fairly obscure).
> (I think I saw something similar in the doc of list.append() too.)

These are all rather old - much of this patch was just moving things
around rather than fixing the prose, although there was plenty of the
latter, too :)

I tried to improve them a bit.

> Is it worth mentioning a function call as an example of syntactic ambiguity?
> Someone might wonder if foo(a, b, c) is actually passing a 3-elements tuple
> or 3 distinct values.

Done.

> This claim is maybe a bit too strong.  I think the main reason to use
> namedtuples is being able to access the elements via t.name, rather than
> t[pos], and while this can be useful for basically every heterogeneous
> tuple, I think that plain tuples are still preferred.

Reworded.

> On a separate note, should tuple unpacking be mentioned here? (a link to a
> separate section of the doc is enough.)

Not really - despite the name, tuple unpacking isn't especially
closely related to tuples these days.

> I would mention explicitly "in :keyword:`for` loops" -- ranges don't loop on
> their own (I think people familiar with Ruby and/or JQuery might get
> confused here).

Done.

> I thought that these two paragraphs were talking about positive and negative
> start/stop/step until I reached the middle of the second paragraph (the word
> "indices" wasn't enough to realize that these paragraphs are about
> indexing/slicing, probably because they are rarely used and I wasn't
> expecting to find them at this point of the doc).  Maybe it's better to move
> the paragraphs at the bottom of the section.

For the moment, I've just dumped the old range builtin docs into this
section. They need a pass to remove the duplication and ensure
everything makes sense in context.

>> +String literals that are part of a single expression and have only
>> whitespace
>> +between them will be implicitly converted to a single string literal.
>> +
>
>
> Is it a string /literal/ they are converted to?
Yup:

>>> ast.dump(compile('"hello world"', '', 'eval', flags=ast.PyCF_ONLY_AST))
"Expression(body=Str(s='hello world'))"
>>> ast.dump(compile('"hello" " world"', '', 'eval', flags=ast.PyCF_ONLY_AST))
"Expression(body=Str(s='hello world'))"

> Anyway a simple ('foo' 'bar') == 'foobar' example might make this sentence
> more understandable.

Added.

>> +There is also no mutable string type, but :meth:`str.join` or
>> +:class:`io.StringIO` can be used to efficiently construct strings from
>> +multiple fragments.
>> +
>
> str.format() deserves to be mentioned here too.

For the kinds of strings where quadratic growth is a problem,
str.format is unlikely to be appropriate.

> I noticed that here there's this fairly long section about the "old" string
> formatting and nothing about the "new" formatting.  Maybe this should be
> moved together with the new formatting doc, so that all the detailed
> formatting docs are in the same place. (This would also help making this
> less noticeable)

Probably. There are a lot of structural problems in the current docs,
because the layout hasn't previously changed to suit the language
design changes.

>> +While bytes literals and representations are based on ASCII text, bytes
>> +objects actually behave like immutable sequences of integers, with each
>> +value in the sequence restricted such that ``0 <= x < 256`` (attempts to
>
> Earlier you used 0 <= x <= 255.

The current docs are the result of many merges, much of which I didn't
write. This is only the start of improving them by breaking away from
the old 1.x structure with a few autocratic decisions on my part to
establish a new layout that makes more sense given the evolution of
the language, especially the big changes in 2.2 and 3.0 :)

> Using ``'abc'.replace('a', 'f')`` and ``b'abc'.replace(b'a', b'f')`` inline
> would be better IMHO, given that the current note takes lot of space to
> explain a trivial concept.

Stylistics edits are always fair game, they don't have to be made by
me. While I skipped a lot of your specific suggestions that weren't
correcting actual errors, that doesn't mean I'm especially opposed to
them, just that I didn't like them enough to implement myself :)

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia