The function does what again?

too_many_usernames

I've been tasked with updating some API documentation that was originally generated by a different supplier (e.g., we work for company A, that had company B do some work. Now we're picking up where B left off.)

The line from the API documentation that has me going "WTF?!" is this beauty:

"And in case if the application issues an IOTCL of clear Tx buffer and if write message is blocked (non zero timeout) then it cannot accept IOCTL till write message function is returned."

What's scary is I know exactly what the code does, and I still don't know how to interpret this statement. It's getting the big-ol' DELETED! edit...

(For the curious, the intended behavior is: If you call a blocking write function with a timeout and from another thread with access to the device in question issue a "ClearTX" I/O control, the pending write will be terminated and the blocked call will return.)

Kemp

Is it wrong that I've read enough badly written docs that that line makes perfect sense to me?

Also, you were looking for i.e. not e.g. ;-)

too_many_usernames

@Kemp said:

Also, you were looking for i.e. not e.g. ;-)

Actually, I *did* mean e.g., because my example was an example and not a direct explanation of what was going on... one of the rare contexts where either is actually accurate, although potentially misleading. I think it's because in my mind I was thinking "let's give an example of a situation similar to the one I want to describe"... oh, well!

And I have to say that I'm sad you have read enough bad docs that you made sens of that line...

Kemp

Ah, k. The use of "we" made me think it was an actual description with the company names removed. I can't think of a concise way to not use "we" though.

As for deciphering it, I blame years of instruction manuals written by people whose first language isn't English (or who don't actually speak it at all), the same deal with some of my old lecturers, and a lot more engrish websites, literal translations and foreign acquaintances than I care to count.

DaveK1

@too_many_usernames said:

The line from the API documentation that has me going "WTF?!" is this beauty:

"And in case if the application issues an IOTCL of
clear Tx buffer and if write message is blocked (non zero timeout) then it
cannot accept IOCTL till write message function is returned."

What's scary is I know exactly what the code does, and I still don't know how to interpret this statement.

I think it means

If you call a blocking write function with a timeout and from another thread with access to the device in question issue a "ClearTX" I/O control, the

ClearTx I/O control cannot complete until the

pending write

has

terminated and the blocked call

has

return

ed.

(although whether that corresponds to the actual behaviour or the intended behaviour I can't guess from your description). Perhaps it describes what an earlier version of the software used to do and it wasn't updated when the code was?

savar

@Kemp said:

Is it wrong that I've read enough badly written docs that that line makes perfect sense to me?

Also, you were looking for i.e. not e.g. ;-)

E.g., I.e., F*ck you! The point is that when I say "jump", you say "okay", okay?