[docs] Bug: I can't find documentation for the "apply" function, and then I can't find documentation for "extended call syntax"

[Zachary Ware]

On Sun, Nov 18, 2012 at 11:44 AM, Kevin Leeds <knleeds at gmail.com> wrote:
> Thank you!
> I think I was deluded perhaps thinking "apply" was a Python function?

apply() is in fact a Python 2 function, as is everything else at
http://docs.python.org/2/library/functions.  However, as you've seen,
it is deprecated and was removed in Python 3.

> It turned out "map" is what I wanted at the time, actually.
> Still I find the function search capability or function index to be
> somewhat deficient in this area.  The documentation didn't seem to
> tell me definitively what "apply" or "map" is or isn't.

That should be covered by the "Built-in Functions" page I linked to
above.  Do you have any specific suggestions for how to improve it?

> I DO
> appreciate that the documentation is to be constructed to be readable
> by programmers who do not wish to be confronted by reams of hard
> technical categories, and mainly want to get something done fast.

True, but we also try to keep the documentation very newbie-friendly.
Anyone who has thoroughly read the tutorial should be able to
understand the reference docs, and if not (or at least if not after
having asked on python-list at python.org or tutor at python.org and gotten
an explanation), the docs should be clarified.

> The
> course I am in is at the level where the correct answer is to use a
> "for" loop.  The course is at too Beginner a level for me, so that is
> my situation.  MIT Open Courseware, Python for beginning programmers -
> but I'm not one of those, taking it anyway to see what chaos can
> ensue! - My version for that course is 2.7.

Another thing to be sure of is that you are in fact looking at the
right documentation.  The docs site was recently changed to redirect
"docs.python.org" to "docs.python.org/3/", the Python 3 doc site. You
can check (and change) which version you're using in the top left of
the page.

> Thank you very much for your helpful reply!

You're very welcome :)

-- Zachary Ware

> Just my 2 cents
> I see there is a Bug Report so I will go visit that right away. Thank
> you Zachary.
> Kevin Leeds
>
> On Sun, Nov 18, 2012 at 11:36 AM, Zachary Ware
> <zachary.ware+pydocs at gmail.com> wrote:
>> On Wed, Nov 14, 2012 at 6:12 PM, Kevin Leeds <knleeds at gmail.com> wrote:
>>> P.S. I still can't find it when I read the Python Tutorial.
>>> There's a section on Defining Functions, then there's More About
>>> Defining Functions.
>>> However there's no section about calling functions.
>>>
>>>
>>> On Wed, Nov 14, 2012 at 5:40 PM, Kevin Leeds <knleeds at gmail.com> wrote:
>>>> Sorry! I am trying to figure out from the documentation a good way to
>>>> use "call" instead of "apply", and am finding myself frustrated by the
>>>> documentation site
>>>>
>>>> Apparently there's no way to search among functions names only, and
>>>> perhaps not for phrases either.
>>>>
>>>> On one page I found out the "apply" function is deprecated, and that I
>>>> should use the "extended call syntax".
>>>> At one point I'm informed that the description of "extended call
>>>> syntax" is described "above".
>>>>
>>>> There should be a hyperlink to the actual description.  It's not
>>>> possible to find the material being referenced without guessing
>>>> sections or reading the entire document perhaps.
>>>>
>>>> :) Thank you for your prompt attention to this important matter :)
>>
>>
>> Hi Kevin,
>>
>> I think the section you're looking for is
>> http://docs.python.org/2.7/tutorial/controlflow.html#arbitrary-argument-lists
>> (or the Python 3 version thereof).
>>
>> Could you give some more information about what version of Python
>> you're using, which pages you're looking at (and which versions),
>> etc.?  The more we know about your situation, the better able we are
>> to make the docs clearer for the next reader :).
>>
>> In the meantime, I've filed an issue on the Python Bug Tracker to
>> track this issue: http://bugs.python.org/issue16503
>>
>> Thanks for the report!