Driver documentation update

libuavcan/include/uavcan/driver/can.hpp

@@ -83,7 +83,7 @@ struct UAVCAN_EXPORT CanFrame
 
 /**
  * CAN hardware filter config struct.
- * Masks from @ref CanFrame can be applied to define frame type (EFF, EXT, etc.).
+ * Flags from @ref CanFrame can be applied to define frame type (EFF, EXT, etc.).
  * @ref ICanIface::configureFilters().
  */
 struct UAVCAN_EXPORT CanFilterConfig
@@ -141,22 +141,30 @@ public:
 
     /**
      * Non-blocking transmission.
+     *
      * If the frame wasn't transmitted upon TX deadline, the driver should discard it.
+     *
      * Note that it is LIKELY that the library will want to send the frames that were passed into the select()
      * method as the next ones to transmit, but it is NOT guaranteed. The library can replace those with new
      * frames between the calls.
+     *
      * @return 1 = one frame transmitted, 0 = TX buffer full, negative for error.
      */
     virtual int16_t send(const CanFrame& frame, MonotonicTime tx_deadline, CanIOFlags flags) = 0;
 
     /**
      * Non-blocking reception.
+     *
      * Timestamps should be provided by the CAN driver, ideally by the hardware CAN controller.
+     *
      * Monotonic timestamp is required and can be not precise since it is needed only for
      * protocol timing validation (transfer timeouts and inter-transfer intervals).
+     *
      * UTC timestamp is optional, if available it will be used for precise time synchronization;
      * must be set to zero if not available.
+     *
      * Refer to @ref ISystemClock to learn more about timestamps.
+     *
      * @param [out] out_ts_monotonic Monotonic timestamp, mandatory.
      * @param [out] out_ts_utc       UTC timestamp, optional, zero if unknown.
      * @return 1 = one frame received, 0 = RX buffer empty, negative for error.
@@ -166,6 +174,7 @@ public:
 
     /**
      * Configure the hardware CAN filters. @ref CanFilterConfig.
+     *
      * @return 0 = success, negative for error.
      */
     virtual int16_t configureFilters(const CanFilterConfig* filter_configs, uint16_t num_configs) = 0;
@@ -177,6 +186,7 @@ public:
 
     /**
      * Continuously incrementing counter of hardware errors.
+     * Arbitration lost should not be treated as a hardware error.
      */
     virtual uint64_t getErrorCount() const = 0;
 };
@@ -194,6 +204,10 @@ public:
      */
     virtual ICanIface* getIface(uint8_t iface_index) = 0;
 
+    /**
+     * Default implementation of this method calls the non-const overload of getIface().
+     * Can be overriden by the application if necessary.
+     */
     virtual const ICanIface* getIface(uint8_t iface_index) const
     {
         return const_cast<ICanDriver*>(this)->getIface(iface_index);
@@ -207,10 +221,19 @@ public:
 
     /**
      * Block until the deadline, or one of the specified interfaces becomes available for read or write.
+     *
      * Iface masks will be modified by the driver to indicate which exactly interfaces are available for IO.
+     *
      * Bit position in the masks defines interface index.
+     *
      * Note that it is allowed to return from this method even if no requested events actually happened, or if
      * there are events that were not requested by the library.
+     *
+     * The pending TX argument contains an array of pointers to CAN frames that the library wants to transmit
+     * next, per interface. This is intended to allow the driver to properly prioritize transmissions; many
+     * drivers will not need to use it. If a write flag for the given interface is set to one in the select mask
+     * structure, then the corresponding pointer is guaranteed to be valid (not NULL).
+     *
      * @param [in,out] inout_masks        Masks indicating which interfaces are needed/available for IO.
      * @param [in]     pending_tx         Array of frames, per interface, that are likely to be transmitted next.
      * @param [in]     blocking_deadline  Zero means non-blocking operation.

libuavcan/include/uavcan/driver/system_clock.hpp

@@ -23,23 +23,34 @@ public:
 
     /**
      * Monototic system clock.
-     * This shall never jump during UTC timestamp adjustments; the base time is irrelevant.
+     *
+     * This clock shall never jump or change rate; the base time is irrelevant.
+     * This clock is mandatory and must remain functional at all times.
+     *
      * On POSIX systems use clock_gettime() with CLOCK_MONOTONIC.
      */
     virtual MonotonicTime getMonotonic() const = 0;
 
     /**
-     * UTC clock.
+     * Global network clock.
-     * This can jump when the UTC timestamp is being adjusted.
+     * It doesn't have to be UTC, the name is a bit misleading - actual time base doesn't matter.
-     * Return 0 if the UTC time is not available yet (e.g. the device just started up with no battery clock).
+     *
-     * On POSIX systems use gettimeofday().
+     * This clock can be synchronized with other nodes on the bus, hence it can jump and/or change
+     * rate occasionally.
+     * This clock is optional; if it is not supported, return zero. Also return zero if the UTC time
+     * is not available yet (e.g. the device has just started up with no battery clock).
+     *
+     * For POSIX refer to clock_gettime(), gettimeofday().
      */
     virtual UtcTime getUtc() const = 0;
 
     /**
-     * Set the UTC system clock.
+     * Adjust the network-synchronized clock.
-     * @param [in] adjustment Amount of time to add to the clock value.
+     * Refer to @ref getUtc() for details.
+     *
      * For POSIX refer to adjtime(), settimeofday().
+     *
+     * @param [in] adjustment Amount of time to add to the clock value.
      */
     virtual void adjustUtc(UtcDuration adjustment) = 0;
 };