CURLOPT_READFUNCTION documentation error

[ghost]

On this page

https://curl.haxx.se/libcurl/c/CURLOPT_READFUNCTION.html

1. The Description section refers to parameter "nmemb" but the function prototype parameter is "nitems".

2. The Return Value section is confusing as the return value (as described in the Description section) is supplied by the user.

[bagder]

Thanks!

The nmemb is clearly a mistake and I'll fix.

The return code however is a bit complicated. When this option is set, curl_easy_setopt() is called and the return code section thus describes what that curl_easy_setopt() call returns. The callback's return code is explained the DESCRIPTION section. This is done like this for all man pages for options that describe callback functions. Any suggestions on how we could make that clearer or less confusing?

[bagder]

So, no suggestion after three weeks and I personally think it is pretty clear...

[ghost]

Daniel, I did offer up my suggestions back in mid-December. Did you not receive them? I’d be happy to resend them if not. Regards, Brent

…

On 2 Jan 2018, at 21:36, Daniel Stenberg ***@***.***> wrote: So, no suggestion after three weeks and I personally think it is pretty clear... — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2175 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ag5XTk-3KOqhy4tVroner_nWLmgzk0BLks5tGvW-gaJpZM4Q_2NL>.

[bagder]

I did not! Please send them again!

[ghost]

Daniel, The message below (now slightly updated) was sent on December 13th in reply to one of your messages, apparently through GitHub. It’s entirely possible I didn’t follow proper procedure. I simply hit the reply button and composed and sent as I would with any email message. Please excuse my lack of familiarity with the GitHub ecosystem. Hope you get it this time! Regards, Brent Daniel, Because my experience with libcurl (but not C/C++) amounts to barely one week, I would ordinarily be inclined to keep my eyes and ears open and my mouth shut regarding anything I found confusing. But since you specifically asked, I will volunteer the following. In my opinion, the place to document the return value of curl_easy_setopt is on the page that documents the function itself (and it is), and not on pages of the various options that function takes. When a particular option requires (a pointer to) a callback function, any mention of a return value there makes me think it’s the callback function’s return value we’re talking about, not curl_easy_setopt. The Description section of CURLOPT_WRITEFUNCTION made sense to me, until I read the Return Value section further down. While we’re on the subject, can you please explain the purpose of having two parameters in the callback function pertaining to buffer size, and what does nmemb stand for? When I first saw it, I found it reminiscent of fwrite with its size and count parameters, but nmemb makes me think of (struct and union) members, not array elements. I might suggest it be changed to something like nelements or count instead, unless I’ve misunderstood once again. (Update Jan 2, 2018: If I’m correct, the parameters appear to be patterned after fwrite, which makes sense. But although I’ve been using C for 35+ years, I had never seen the parameter called nmemb until last month when I did a Google search on fwrite. Go figure. If in your judgement the documentation should remain structured as it is, then I would suggest that the Return Value sections of pages like CURLOPT_* be changed to explicitly state that the return value being referred to pertains to curl_easy_setopt, not the callback function. I hope all this helps! Best regards, Brent UTC-6

…

On 2 Jan 2018, at 21:43, Daniel Stenberg ***@***.***> wrote: Reopened #2175 <#2175>. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2175 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ag5XTpv8bNkZOZDGMZQ-shqGQLf6VQp8ks5tGvdLgaJpZM4Q_2NL>.

[bagder]

First: the argument is not called nmemb anymore, and yes the read/write callbacks are completely made up like fread/fwrite. A decision we made eons ago. Maybe not the most clever one we've done, but one we can't easily change now... Besides, the name of an argument in a man page is a very arbitrary thing to me and only serves as something to refer back to from the description so it's not a terribly big deal I think.

In regards to RETURN VALUE on the page: that's how we document all options to curl_easy_setopt (and in fact the other two *setopt functions too). It is actually not that common to have stand-alone man pages for separate options to functions to this is an area where we can't compare with a lot of other pre-existing documentation.

In my head, the documentation is for what happens when setopt is called using that option, so that's the return value. But I understand your point here. I just don't see an easy fix.

changed to explicitly state that the return value being referred to pertains to curl_easy_setopt, not the callback function.

I'd prefer all options pages to use the same style/language, and most options don't set any callback pointer.

Maybe we should have a separate CALLBACK header that describes exactly what the callback is supposed to do and then CALLBACK RETURN VALUE that describes what the callback can return and how those values are treated by libcurl? (Those could then be used for all options man pages that describe setting callbacks, some 10-12 of them or so.)

[bagder]

While we can (should?) improve the documentation and I'll welcome that, I don't think this is a bug so I'm now closing this issue.