On 20-Apr-23 07:01, Andreas Falkenhahn via curl-library wrote:
On 20.04.2023 at 12:31 Timothe Litt via curl-library wrote:If there are any cases where the string is not copied and must be retained, the documentation should say so explicitly.+1 To make matters more confusing, I've also found this information: "There are currently over 80 options for curl_easy_setopt() that accept a string as its third argument. When a string is set in a handle, libcurl immediately copies that data so that the application does not have to keep the data around for the time the transfer is being done - with one notable exception: CURLOPT_POSTFIELDS." Found here:https://everything.curl.dev/libcurl/options/strings If that is true, maybe the note "The application does not have to keep the string around after setting this option" should be killed from all CURLOPT_* pages and there should only be a note for CURLOPT_POSTFIELDS that says that the string isn't copied.
I think it's better to state how the string is managed with each option - people look at the option page when using an option, but the general info page only once (if ever).
Some documents use flags or icons for argument characteristics to avoid repetitive text.
There could be a standard block for the argument, perhaps something like: Argument:Type: byte string, utf-8 string, (pointer to) signed long, unsigned long, structure, enum, unused,...
Usage: Input, Output, Input/Output Managed: cURL copies, user retains Range: min - max
OpenPGP_signature
Description: OpenPGP digital signature
-- Unsubscribe: https://lists.haxx.se/mailman/listinfo/curl-library Etiquette: https://curl.se/mail/etiquette.html