cmdline: big rework and clean of cmdline library

[libcmdline.git] / src / lib / cmdline.h

diff --git a/src/lib/cmdline.h b/src/lib/cmdline.h
index d8a7384..20321e8 100644 (file)
--- a/src/lib/cmdline.h
+++ b/src/lib/cmdline.h
@@ -75,13 +75,59 @@ struct cmdline {
 #endif
 };
 
-struct cmdline *cmdline_new(cmdline_parse_ctx_t *ctx, const char *prompt, int s_in, int s_out);
+/**
+ * Allocate and initialize a new command line structure, using the
+ * specified prompt and specified input/output file descriptors to
+ * communicate with the user.
+ */
+struct cmdline *cmdline_new(cmdline_parse_ctx_t *ctx, const char *prompt,
+                           int s_in, int s_out);
+
+/**
+ * Set the prompt of the given command line.
+ */
 void cmdline_set_prompt(struct cmdline *cl, const char *prompt);
+
+/**
+ * Free a previously allocated command line: data pointed by the cl
+ * pointer is freed. Note: the user should call cmdline_quit() before
+ * calling this function.
+ */
 void cmdline_free(struct cmdline *cl);
-void cmdline_printf(const struct cmdline *cl, const char *fmt, ...);
+
+/**
+ * write a buffer, just use rdline
+ */
+ssize_t cmdline_write(void *arg, void *buf, size_t count);
+
+/**
+ * Display data on the output file descriptor of command line, using
+ * printf-like arguments.
+ */
+int cmdline_printf(const struct cmdline *cl, const char *fmt, ...);
+
+/**
+ * Push an input buffer in the command line. Typically, this function
+ * is called by cmdline_interact() to send the inpu characters to the
+ * cmdline process. It can also be called by a user callback function,
+ * when a buffer is received from the input socket.
+ *
+ * The function returns the number of processed characters, or a
+ * negative value on error (EOF reached or command line exited.
+ */
 int cmdline_in(struct cmdline *cl, const char *buf, int size);
-int cmdline_write_char(struct rdline *rdl, char c);
+
+/**
+ * Start command line on configured file descriptor. This function
+ * loops until the user explicitelly call cmdline_quit(), or if the
+ * input fd reaches EOF.
+ */
 void cmdline_interact(struct cmdline *cl);
+
+/**
+ * Interrupt a running command line process. Actually it will call
+ * rdline_quit() on the rdline descriptor.
+ */
 void cmdline_quit(struct cmdline *cl);
 
 #endif /* _CMDLINE_SOCKET_H_ */