clock: review all API comments; See #71