The function does what again?



  • 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.)



  • 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. ;-)



  • @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...



  • 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.



  • @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?

     



  • @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?


Log in to reply
 

Looks like your connection to What the Daily WTF? was lost, please wait while we try to reconnect.