PyWart: Poor Documentation Examples

[Rustom Mody]

On Sunday, January 11, 2015 at 10:56:11 AM UTC+5:30, Devin Jeanpierre wrote:
> On Sat, Jan 10, 2015 at 6:32 PM, Steven D'Aprano wrote:
> > At the point you are demonstrating reduce(), if the reader doesn't
> > understand or can't guess the meaning of "n = 4", "n+1" or range(), they
> > won't understand anything you say.
> >
> > Teachers need to understand that education is a process of building upon
> > that which has come before. If the teacher talks down to the student by
> > assuming that the student knows nothing, and tries to go back to first
> > principles for every little thing, they will never get anywhere.
> 
> Agree wholeheartedly. That said, I do think reduce(operator.mul, [1,
> 2, 3, 4]) actually _is_ a better example, since it cuts right to the
> point.

In keeping with Rick's super-polite suggestion to remove
irreleventia like range and variables(!), if we are about to
improve that doc, I would remove the
1,2,3,4
pattern as well and replace with something more random.

The mathematically minded student may think that this has something
to do with arithmetic progressions,
that it does clever algebraic simplifications like
𝚺 i = n(n+1)/2

A favorite example of mine is automata-acceptance:
If 
δ : Q × Σ → Q is a transition function
F is the set of final states
q₀ is the start state
and s is a string

then
reduce(δ,q₀,s) ∈ F
expresses "automaton accepts string s"

Should that go into the doc??
I'll leave that to somebody else whose name starts with 'R' :-)