[docs] Profile objects should be documented (issue 6696)

[ezio.melotti at gmail.com]

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst
File Doc/library/profile.rst (left):

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#oldcode10
Doc/library/profile.rst:10: :synopsis: Python source profiler.
Why have you removed these?

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst
File Doc/library/profile.rst (right):

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode8
Doc/library/profile.rst:8: :source:`Modules/_lsprof.c` and
:source:`Lib/pstats.py`
:source:`Lib/cProfile.py` and :source:`Modules/_lsprof.c` shouldn't be
included IMHO.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode63
Doc/library/profile.rst:63: cProfile.run('foo(x)')
Why this change?
It seems easier to me to say that if you want to profile the function
foo you can call .run('foo()').

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode77
Doc/library/profile.rst:77: 43/3    0.533    0.012    0.749    0.250
pobject.py:99(evaluate)
I think it would be even better to use a real-world example that users
can run (maybe you can thing about something better than re.compile),
e.g.:
>>> import cProfile
>>> import re
>>> cProfile.run('re.compile("foo|bar")')
         197 function calls (192 primitive calls) in 0.002 seconds

   Ordered by: standard name

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
        1    0.000    0.000    0.001    0.001 <string>:1(<module>)
        1    0.000    0.000    0.001    0.001 re.py:212(compile)
        1    0.000    0.000    0.001    0.001 re.py:268(_compile)
        1    0.000    0.000    0.000    0.000
sre_compile.py:172(_compile_charset)
        1    0.000    0.000    0.000    0.000
sre_compile.py:201(_optimize_charset)
        4    0.000    0.000    0.000    0.000
sre_compile.py:25(_identityfunction)
      3/1    0.000    0.000    0.000    0.000
sre_compile.py:33(_compile)

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode104
Doc/library/profile.rst:104: provides the respective data of each
function
The end of lines are inconsistent.  You can remove the trailing commas
and full stop.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode280
Doc/library/profile.rst:280: Profile the cmd via :func:`exec` with the
specified global and local environment.
Line too long (there are a few others that are longer than 80 chars
too).

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode397
Doc/library/profile.rst:397: +------------------+----------------------+
Here you could use the simpler table syntax:
====== ======
header header
====== ======
row1   row1
row2   row2
...    ...
====== ======

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode418
Doc/library/profile.rst:418: .. For compatibility with the old profiler,
s/,/./

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode447
Doc/library/profile.rst:447: printed; as of Python 1.5b1, this uses the
Perl-style regular
This can probably be removed.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode618
Doc/library/profile.rst:618: interpreted differently:
This could point to the different times available in the time module,
and possibly provide some suggestion.

http://bugs.python.org/review/6696/