[libc] make clock_conversion.h common and document it

clock_conversion.h implements convert_clock which shifts a timestamp from
one clock domain to another. It naturally does not depend on any OS specific
interface. Making it generic will allow common use.

Author: bojle

libc/src/__support/time/linux/clock_conversion.h renamed to libc/src/__support/time/clock_conversion.h

@@ -1,10 +1,10 @@
-//===--- clock conversion linux implementation ------------------*- C++ -*-===//
+//===--- clock conversion implementation ------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
-//===----------------------------------------------------------------------===//
+//===----------------------------------------------------------------===//
 
 #ifndef LLVM_LIBC_SRC___SUPPORT_TIME_LINUX_CLOCK_CONVERSION_H
 #define LLVM_LIBC_SRC___SUPPORT_TIME_LINUX_CLOCK_CONVERSION_H
@@ -16,6 +16,28 @@
 namespace LIBC_NAMESPACE_DECL {
 namespace internal {
 
+/**
+ * @brief Convert a timespec value from one clock domain to another.
+ *
+ * The function takes a timestamp that is expressed in terms of the clock
+ * identified by param from and returns an equivalent timestamp expressed
+ * in terms of the clock identified by param to.
+ *
+ * Internally it obtains the current time of both clocks with
+ * clock_gettime, then subtracts the source clock’s value and
+ * adds the target clock’s value. The result is normalised so that
+ * the nanoseconds field is always in the range [0, 1 s).
+ *
+ * This is useful, for example, for converting a value obtained from
+ * CLOCK_MONOTONIC to CLOCK_REALTIME (or vice‑versa) so that the
+ * timestamp can be displayed to a user or stored in a format that
+ * is independent of the original clock domain.
+ *
+ * @param input The timestamp to convert
+ * @param from Clock ID of the original timestamp (e.g. CLOCK_MONOTONIC).
+ * @param to Clock ID of the desired timestamp (e.g. CLOCK_REALTIME).
+ * @return The converted timespec
+ */
 LIBC_INLINE timespec convert_clock(timespec input, clockid_t from,
                                    clockid_t to) {
   using namespace time_units;

libc/src/__support/time/linux/monotonicity.h

@@ -12,8 +12,8 @@
 #include "hdr/time_macros.h"
 #include "src/__support/libc_assert.h"
 #include "src/__support/macros/config.h"
+#include "src/__support/time/clock_conversion.h"
 #include "src/__support/time/linux/abs_timeout.h"
-#include "src/__support/time/linux/clock_conversion.h"
 namespace LIBC_NAMESPACE_DECL {
 namespace internal {
 // This function is separated from abs_timeout.