Re: [PATCH v4 02/25] ibtrs: public interface header to establish RDMA connections

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On 9/25/19 3:20 AM, Danil Kipnis wrote:
On Mon, Sep 23, 2019 at 7:44 PM Bart Van Assche <bvanassche@xxxxxxx> wrote:
+/**
+ * ibtrs_clt_open() - Open a session to a IBTRS client
+ * @priv:            User supplied private data.
+ * @link_ev:         Event notification for connection state changes
+ *   @priv:                  user supplied data that was passed to
+ *                           ibtrs_clt_open()
+ *   @ev:                    Occurred event
+ * @sessname: name of the session
+ * @paths: Paths to be established defined by their src and dst addresses
+ * @path_cnt: Number of elemnts in the @paths array
+ * @port: port to be used by the IBTRS session
+ * @pdu_sz: Size of extra payload which can be accessed after tag allocation.
+ * @max_inflight_msg: Max. number of parallel inflight messages for the session
+ * @max_segments: Max. number of segments per IO request
+ * @reconnect_delay_sec: time between reconnect tries
+ * @max_reconnect_attempts: Number of times to reconnect on error before giving
+ *                       up, 0 for * disabled, -1 for forever
+ *
+ * Starts session establishment with the ibtrs_server. The function can block
+ * up to ~2000ms until it returns.
+ *
+ * Return a valid pointer on success otherwise PTR_ERR.
+ */
+struct ibtrs_clt *ibtrs_clt_open(void *priv, link_clt_ev_fn *link_ev,
+                              const char *sessname,
+                              const struct ibtrs_addr *paths,
+                              size_t path_cnt, short port,
+                              size_t pdu_sz, u8 reconnect_delay_sec,
+                              u16 max_segments,
+                              s16 max_reconnect_attempts);

Having detailed kernel-doc headers for describing API functions is great
but I'm not sure a .h file is the best location for such documentation.
Many kernel developers keep kernel-doc headers in .c files because that
makes it more likely that the documentation and the implementation stay
in sync.
>
What is better: to move it or to only copy it to the corresponding C file?

Please move the kernel-doc header into the corresponding .c file and remove the kernel-doc header from the .h file.

Thanks,

Bart.



[Index of Archives]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Photo]     [Yosemite News]     [Yosemite Photos]     [Linux Kernel]     [Linux SCSI]     [XFree86]

  Powered by Linux