On Tue, Jun 26, 2018 at 2:24 AM, Dave Chinner david@fromorbit.com 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@fromorbit.com 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