On Tue, Jun 26, 2018 at 2:24 AM, Dave Chinner <david@xxxxxxxxxxxxx> wrote:
> On Fri, Jun 22, 2018 at 03:24:48PM +0200, Arnd Bergmann wrote:
>> On Thu, Jun 21, 2018 at 10:23 PM, Dave Chinner <david@xxxxxxxxxxxxx> wrote:
>> > On Wed, Jun 20, 2018 at 05:01:24PM +0200, Arnd Bergmann wrote:
>> You definitely have a point about the documentation. I meant to
>> fix that as part of the recent rework of the timekeeping.h header
>> but haven't finished it, partly because the header is still being
>> changed as we get rid of the older interfaces.
>
> The interface documentation should be introduced with the new
> interfaces, not left for later as that leaves people like me with no
> fucking clue about what the changes actually mean or why they are
> being done. Perhaps you'd have done better to explain this API as
> an internal implementation of clock_gettime(CLOCK_REALTIME_COARSE),
> which is clearly documented in the man page as:
>
> "Use when you need very fast, but not fine-grained timestamps."
>
> Put that comment on ktime_get_coarse_real_ts64(), and almost all the
> questions about "WTF does this whacky function do?" go away....
I've tried to come up with a coherent documentation now and sent a
patch for that. For this version, I ended up not documenting each of the
ktime_get() functions separately but instead added a new file in the
core-api documentation and a reference to that from the header. This
seemed easier to understand than duplicating the same text for over
30 very similar interfaces.
Arnd
