Re: [PATCH v2 0/4] clodkid and abs mode CQ wait timeouts

[Pavel Begunkov <asml.silence@gmail.com>]

On 8/13/24 03:09, Jens Axboe wrote:
> On 8/12/24 7:32 PM, Pavel Begunkov wrote:
>> On 8/13/24 01:59, Jens Axboe wrote:
>>> On 8/12/24 6:50 PM, Pavel Begunkov wrote:
>>>> On 8/12/24 19:30, Jens Axboe wrote:
>>>>> On 8/12/24 12:13 PM, Jens Axboe wrote:
>>>>>> On 8/7/24 8:18 AM, Pavel Begunkov wrote:
>>>>>>> Patch 3 allows the user to pass IORING_ENTER_ABS_TIMER while waiting
>>>>>>> for completions, which makes the kernel to interpret the passed timespec
>>>>>>> not as a relative time to wait but rather an absolute timeout.
>>>>>>>
>>>>>>> Patch 4 adds a way to set a clock id to use for CQ waiting.
>>>>>>>
>>>>>>> Tests: https://github.com/isilence/liburing.git abs-timeout
>>>>>>
>>>>>> Looks good to me - was going to ask about tests, but I see you have those
>>>>>> already! Thanks.
>>>>>
>>>>> Took a look at the test, also looks good to me. But we need the man
>>>>> pages updated, or nobody will ever know this thing exists.
>>>>
>>>> If we go into that topic, people not so often read manuals
>>>> to learn new features, a semi formal tutorial would be much
>>>> more useful, I believe.
>>>>
>>>> Regardless, I can update mans before sending the tests, I was
>>>> waiting if anyone have feedback / opinions on the api.
>>>
>>> I regularly get people sending corrections or questions after having
>>> read man pages, so I'd have to disagree. In any case, if there's one
>>
>> That doesn't necessarily mean they've learned about the feature from
>> the man page. In my experience, people google a problem, find some
>> clue like a name of the feature they need and then go to a manual
>> (or other source) to learn more.
>>
>> Which is why I'm not saying that man pages don't have a purpose, on
>> the contrary, but there are often more convenient ways of discovering
>> in the long run.
> 
> In my experience, you google if you have very little clue what you're
> doing, to hopefully learn. And you use a man page, if whatever API you're
> using has good man pages, if you're just curius about a specific
> function. There's definitely a place for both.
> 
> None of that changes the fact that the liburing man pages should
> _always_ document all of the API.

Nobody said the opposite, but I don't buy that man pages or lack
of thereof somehow mean "nobody will ever know this thing exists".

-- 
Pavel Begunkov