[Python-Dev] [Python-checkins] cpython: Issue #15502: Finish bringing importlib.abc in line with the current

[Chris Jerdonek]

On Sat, Aug 11, 2012 at 9:40 AM, Georg Brandl <g.brandl at gmx.net> wrote:
> On 08/11/2012 04:49 PM, R. David Murray wrote:
>> On Fri, 10 Aug 2012 16:56:43 -0700, Chris Jerdonek <chris.jerdonek at gmail.com> wrote:
>>> On Fri, Aug 10, 2012 at 9:21 AM, brett.cannon
>>> <python-checkins at python.org> wrote:
>>> > http://hg.python.org/cpython/rev/0a75ce232f56
>>> > changeset:   78485:0a75ce232f56
>>> > user:        Brett Cannon <brett at python.org>
>>> > date:        Fri Aug 10 12:21:12 2012 -0400
>>> > summary:
>>> >   Issue #15502: Finish bringing importlib.abc in line with the current
>>>
>>> > +      cache used by the finder. Used by :func:`invalidate_caches()` when
>>>
>>> Minor style nit: the Dev Guide says not to include the trailing
>>> parentheses in :func: text:
>>>
>>> "func: The name of a Python function; dotted names may be used. The
>>> role text should not include trailing parentheses to enhance
>>> readability..."
>>>
>>> (from http://hg.python.org/devguide/file/f518f23d06d5/documenting.rst#l888 )
>>>
>>> (though I don't know why the Dev Guide says the opposite for :c:func:
>>> and is silent on :meth:.)
>>
>> To clarify: :func: automatically adds the ()s, so if you put them in
>> the source you get double: invalidate_caches()().
>
> That is not true: they are stripped if present before they are added again.

Yes, and the Dev Guide in part says this afterward.  Its statement not
to include trailing parentheses to enhance readability was I assume
for readability of the .rst files rather than readability of the
output.

--Chris

> What will give double parens is if you don't leave them empty, such as
> :func:`invalidate_caches(foo)`.  This is because the reference markup is not
> meant for code snippets.
>
> Georg
>
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/chris.jerdonek%40gmail.com