I2ctarget doc function request: a) mods to doc text & function signature. b) small mod of the code

[PaulskPt]

Intro

First a remark to the choice of the name of my branch 'i2ctarget_doc_text_mod'. This title was chosen because, initially, the (first) modification suggested in this PR was limited to the doc text of the function 'request' of the class 'I2CTarget' and the function signature inside that text.
As I will explain below, in this moment, the title of this PR is broader. This PR also contains a suggestion for a small change into the code of the function 'request'.

Subject 1: Initial error

While busy with a test script using the I2CTarget class, a run of my script, when calling the function 'request', resulted in the error 'Extra positional arguments given'

On October 1, at 1:58 pm (utc +1) I posted a question on Discord > Adafruit > circuitpython-dev:

@jepler answered to my question. He explained me that his was caused because of the function signature:

@jepler showed me that the following change would solve the error:

At the end of our conversation @jepler showed me a REPL test output as well as his suggestion to me: 'An issue, or better yet a PR to fix it, would be appreciated from you once you've verified it as well. '

As result of the conversation with @jepler I suggest the following change in the function signature of function 'request':

Subject 2: range parameter timeout

Today, October 3, 2022, I was studying the code of file I2CTarget.c
My attention went in particular to: Class I2CTarget, function: 'request'

While the conversation with @jepler on Discord is the reason for this PR and the suggested change is concerning the doc text preceding the function 'request' and a change of the function signature, today I discovered that the definition of function 'request' defaults parameter 'timeout to -1'. However, the code inside the function checks timeout in the 'if block' for value 0 and - in the 'else if' block - for values > 0. (see below). While the function defaults parameter 'timeout' to -1, the block: ```

if (timeout_ms == 0) {
        forever = true;
    } else if (timeout_ms > 0) {
        timeout_end = common_hal_time_monotonic_ms() + timeout_ms;
    }

does not check for parameter timeout values < 0.
That is why I suggest the following change: ```

if (timeout_ms <= 0) {
        forever = true;
    } else if (timeout_ms > 0) {
        timeout_end = common_hal_time_monotonic_ms() + timeout_ms;
    }

The result of my modification is that parameter 'timeout' now is checked for a full range of possible float values:

(float max negative) <= 0 > (float max positive)

while the current code checks a limited range of values for timeout:

0 > (float max positive)

Final note: concerning the first commit to this branch

To be able to create this PR, online I created a fresh fork of Circuitpython. Next, using the MS Windows 11 Github desktop app, I created a local clone of the fork. Then I created this branch. After the Github desktop app was ready with cloning and arranging things, the app immediately confronted me with a 'change' it assumed I had done in file /ports/broadcom/firmware.

However I did not do such a thing. Since I am not very familiar with the ins and outs of Github commands regarding cloning, creating branches and so on, I did not know what to do with it. Today I discovered that the possible reason for Github desktop app to tell me I made a change in /ports/broadcom/firmware, was that I saw this file being mentioned at the end of the '.gitignore' under 'uncrustify'.
I removed the filename '/ports/broadcom/firmware' entry there, resulting in:

Now the contents of the .gitignore file in this branch (at least the last few lines of it) is equal to the contents of the .gitignore file of the 'main' branch of the 'circuitpython repo.

This ends my description of the reasons for creating this PR and the examples/clarifications to the matter.
I thank @jepler for his replies, assistance and to 'push' me (kindly) to create this PR.

Lisbon, October, 3, 4:16 pm local (utc +1),
Paulus Schulinck, @PaulskPt

[jepler]

Thanks! I fixed tests/pyboard.py which was incorrectly modified as part of this PR.

[PaulskPt]

Again thank you Jeff.

[s-ol]

Hey, I think the check timeout == 0 and timeout > 0 is intentional: -1 (do not block) is not the same as 0 (block indefinitely).

When timeout is -1, forever should be false. This change should be reverted to resolve #7241 and restore functionality as documented:

timeout (float) - Timeout in seconds. Zero means wait forever, a negative value means check once