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.
