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

[Georg Brandl]

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.

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