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

[R. David Murray]

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()().  As Chris said,
use the 'alternate text' form if you want to show a call with arguments.

--David