Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
CURLOPT_READFUNCTION documentation error #2175
On this page
The return code however is a bit complicated. When this option is set,
added a commit
Dec 13, 2017
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>.
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>.
First: the argument is not called
In regards to RETURN VALUE on the page: that's how we document all options to
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.
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.)