[docs] [issue24466] extend_path explanation in documentation is ambiguous

[alanf]

New submission from alanf:

The description of pkgutil.extend_path in the doc (e.g., https://docs.python.org/2/library/pkgutil.html , https://docs.python.org/3/library/pkgutil.html ) is so ambiguous that I had to run a test to understand its behavior.

The doc says:

This will add to the package’s __path__ all subdirectories of directories on sys.path named after the package.

It wasn't clear to me how this should be parsed. Using parentheses to group the clauses, there's this possibility :

(1) This will add to the package’s __path__ all (subdirectories of directories on sys.path) named after the package.

That is, given all subdirectories of directories on sys.path, find the ones that are named after the package, and add them to the package's __path__.

or:

(2) This will add to the package’s __path__ all subdirectories of (directories on sys.path named after the package).

That is, given all directories on sys.path that are named after the package, add all their subdirectories to the package's __path__.

or: 

(3) This will add to the package’s __path__ all subdirectories of ((directories on sys.path) named after the package).

That is, given all directories on sys.path that are named after the package, add all their subdirectories to the package's __path__.

or:

(4) This will add to the package’s __path__ all (subdirectories of (directories on sys.path)) named after the package.

That is, given all directories on sys.path, add any of their subdirectories that are named after the package to the package's __path__.

It was also unclear to me whether the subdirectories were meant to be traversed recursively.

My testing indicates that (4) is the correct parse, and that the subdirectories are not meant to be traversed recursively.

I suggest this wording: For each directory on sys.path that has a subdirectory that matches the package name, add the subdirectory to the package's __path__.

----------
assignee: docs at python
components: Documentation
messages: 245468
nosy: alanf, docs at python
priority: normal
severity: normal
status: open
title: extend_path explanation in documentation is ambiguous
type: enhancement
versions: Python 2.7, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24466>
_______________________________________