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

[Tom Pinckney]

Thanks for the helpful feedback. I'll review and submit an updated patch this weekend.

On Apr 3, 2013, at 8:26 PM, ezio.melotti at gmail.com wrote:

> 
> 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/