Argument Clinic How-To needs more examples

[littlebutt]

Documentation

Currently, the example for AC How-To is the method _pickle.Pickler.dump. I think it is not proper since it cannot cover all cases and makes readers confused. A more intuitive example should be considered to replace the current one.

Linked PRs

• gh-106799: Pick another example method for Argument Clinic How-To cpython#106800

[erlend-aasland]

I think it is not proper since it cannot cover all cases and makes readers confused. A more intuitive example should be considered to replace the current one.

Can you elaborate? Which cases are not covered, what is confusing, and what is a more intuitive example? :)

[littlebutt]

I think it is not proper since it cannot cover all cases and makes readers confused. A more intuitive example should be considered to replace the current one.

Can you elaborate? Which cases are not covered, what is confusing, and what is a more intuitive example? :)

In the chapter Converting Your First Function, some steps don't have Sample. For example, in step 5, it says:

(Our example docstring consists solely of a summary line, so the sample code doesn’t have to change for this step.)

In step 9, it says:

(_pickle.Pickler.dump has neither, so our sample is unchanged.)

I picked another function _asyncio.Future.add_done_callback and it can cover these steps rightly. Actually, I refered this function when I was learning AC.