doxygen: Add (partial) VTY API documentation

3 files changed, 122 insertions, 70 deletions

diff --git a/include/osmocom/vty/command.h b/include/osmocom/vty/command.h
index 783a7a2d..c50f256f 100644
--- a/include/osmocom/vty/command.h
+++ b/include/osmocom/vty/command.h
@@ -28,74 +28,80 @@
 #include "vector.h"
 #include "vty.h"
 
-/* Host configuration variable */
+/*! \addtogroup vty
+ *  @{
+ */
+/*! \file command.h */
+
+/*! \brief Host configuration variable */
 struct host {
-	/* Host name of this router. */
+	/*! \brief Host name of this router. */
 	char *name;
 
-	/* Password for vty interface. */
+	/*! \brief Password for vty interface. */
 	char *password;
 	char *password_encrypt;
 
-	/* Enable password */
+	/*! \brief Enable password */
 	char *enable;
 	char *enable_encrypt;
 
-	/* System wide terminal lines. */
+	/*! \brief System wide terminal lines. */
 	int lines;
 
-	/* Log filename. */
+	/*! \brief Log filename. */
 	char *logfile;
 
-	/* config file name of this host */
+	/*! \brief config file name of this host */
 	char *config;
 
-	/* Flags for services */
+	/*! \brief Flags for services */
 	int advanced;
 	int encrypt;
 
-	/* Banner configuration. */
+	/*! \brief Banner configuration. */
 	const char *motd;
 	char *motdfile;
 
+	/*! \brief VTY application information */
 	const struct vty_app_info *app_info;
 };
 
-/* There are some command levels which called from command node. */
+/*! \brief There are some command levels which called from command node. */
 enum node_type {
-	AUTH_NODE,		/* Authentication mode of vty interface. */
-	VIEW_NODE,		/* View node. Default mode of vty interface. */
-	AUTH_ENABLE_NODE,	/* Authentication mode for change enable. */
-	ENABLE_NODE,		/* Enable node. */
-	CONFIG_NODE,		/* Config node. Default mode of config file. */
-	SERVICE_NODE,		/* Service node. */
-	DEBUG_NODE,		/* Debug node. */
-	CFG_LOG_NODE,		/* Configure the logging */
+	AUTH_NODE,		/*!< \brief Authentication mode of vty interface. */
+	VIEW_NODE,		/*!< \brief View node. Default mode of vty interface. */
+	AUTH_ENABLE_NODE,	/*!< \brief Authentication mode for change enable. */
+	ENABLE_NODE,		/*!< \brief Enable node. */
+	CONFIG_NODE,		/*!< \brief Config node. Default mode of config file. */
+	SERVICE_NODE,		/*!< \brief Service node. */
+	DEBUG_NODE,		/*!< \brief Debug node. */
+	CFG_LOG_NODE,		/*!< \brief Configure the logging */
 
-	VTY_NODE,		/* Vty node. */
+	VTY_NODE,		/*!< \brief Vty node. */
 
-	L_E1INP_NODE,		/* E1 line in libosmo-abis. */
-	L_IPA_NODE,		/* IPA proxying commands in libosmo-abis. */
+	L_E1INP_NODE,		/*!< \brief E1 line in libosmo-abis. */
+	L_IPA_NODE,		/*!< \brief IPA proxying commands in libosmo-abis. */
 
 	_LAST_OSMOVTY_NODE
 };
 
-/* Node which has some commands and prompt string and configuration
-   function pointer . */
+/*! \brief Node which has some commands and prompt string and
+ * configuration function pointer . */
 struct cmd_node {
-	/* Node index. */
+	/*! \brief Node index */
 	enum node_type node;
 
-	/* Prompt character at vty interface. */
+	/*! \brief Prompt character at vty interface. */
 	const char *prompt;
 
-	/* Is this node's configuration goes to vtysh ? */
+	/*! \brief Is this node's configuration goes to vtysh ? */
 	int vtysh;
 
-	/* Node's configuration write function */
+	/*! \brief Node's configuration write function */
 	int (*func) (struct vty *);
 
-	/* Vector of this node's command list. */
+	/*! \brief Vector of this node's command list. */
 	vector cmd_vector;
 };
 
@@ -104,26 +110,26 @@ enum {
 	CMD_ATTR_HIDDEN,
 };
 
-/* Structure of command element. */
+/*! \brief Structure of a command element */
 struct cmd_element {
-	const char *string;	/* Command specification by string. */
+	const char *string;	/*!< \brief Command specification by string. */
 	int (*func) (struct cmd_element *, struct vty *, int, const char *[]);
-	const char *doc;	/* Documentation of this command. */
-	int daemon;		/* Daemon to which this command belong. */
-	vector strvec;		/* Pointing out each description vector. */
-	unsigned int cmdsize;	/* Command index count. */
-	char *config;		/* Configuration string */
-	vector subconfig;	/* Sub configuration string */
-	u_char attr;		/* Command attributes */
+	const char *doc;	/*!< \brief Documentation of this command. */
+	int daemon;		/*!< \brief Daemon to which this command belong. */
+	vector strvec;		/*!< \brief Pointing out each description vector. */
+	unsigned int cmdsize;	/*!< \brief Command index count. */
+	char *config;		/*!< \brief Configuration string */
+	vector subconfig;	/*!< \brief Sub configuration string */
+	u_char attr;		/*!< \brief Command attributes */
 };
 
-/* Command description structure. */
+/*! \brief Command description structure. */
 struct desc {
-	const char *cmd;	/* Command string. */
-	const char *str;	/* Command's description. */
+	const char *cmd;	/*!< \brief Command string. */
+	const char *str;	/*!< \brief Command's description. */
 };
 
-/* Return value of the commands. */
+/*! \brief Return value of the commands. */
 #define CMD_SUCCESS              0
 #define CMD_WARNING              1
 #define CMD_ERR_NO_MATCH         2
@@ -171,13 +177,23 @@ struct desc {
   static int funcname \
     (struct cmd_element *self, struct vty *vty, int argc, const char *argv[])
 
-/* DEFUN for vty command interafce. Little bit hacky ;-). */
+/*! \brief Macro for defining a VTY node and function
+ *  \param[in] funcname Name of the function implementing the node
+ *  \param[in] cmdname Name of the command node
+ *  \param[in] cmdstr String with syntax of node
+ *  \param[in] helpstr String with help message of node
+ */
 #define DEFUN(funcname, cmdname, cmdstr, helpstr) \
   DEFUN_CMD_FUNC_DECL(funcname) \
   DEFUN_CMD_ELEMENT(funcname, cmdname, cmdstr, helpstr, 0, 0) \
   DEFUN_CMD_FUNC_TEXT(funcname)
 
-/* global (non static) cmd_element */
+/*! \brief Macro for defining a non-static (global) VTY node and function
+ *  \param[in] funcname Name of the function implementing the node
+ *  \param[in] cmdname Name of the command node
+ *  \param[in] cmdstr String with syntax of node
+ *  \param[in] helpstr String with help message of node
+ */
 #define gDEFUN(funcname, cmdname, cmdstr, helpstr) \
   DEFUN_CMD_FUNC_DECL(funcname) \
   gDEFUN_CMD_ELEMENT(funcname, cmdname, cmdstr, helpstr, 0, 0) \
@@ -350,4 +366,5 @@ void print_version(int print_copyright);
 
 extern void *tall_vty_cmd_ctx;
 
+/*! }@ */
 #endif				/* _ZEBRA_COMMAND_H */
diff --git a/include/osmocom/vty/telnet_interface.h b/include/osmocom/vty/telnet_interface.h
index 1d8055e7..c776f51c 100644
--- a/include/osmocom/vty/telnet_interface.h
+++ b/include/osmocom/vty/telnet_interface.h
@@ -26,15 +26,28 @@
 
 #include <osmocom/vty/vty.h>
 
+/*! \addtogroup vty
+ *  @{
+ */
+
+/*! \file telnet_interface.h */
+
+/*! \brief A telnet connection */
 struct telnet_connection {
+	/*! \brief linked list header for internal management */
 	struct llist_head entry;
+	/*! \brief private data pointer passed through */
 	void *priv;
+	/*! \brief filedsecriptor (socket ) */
 	struct osmo_fd fd;
+	/*! \brief VTY instance associated with telnet connection */
 	struct vty *vty;
+	/*! \brief logging target associated with this telnet connection */
 	struct log_target *dbg;
 };
 
-
 int telnet_init(void *tall_ctx, void *priv, int port);
 
-#endif
+/*! }@ */
+
+#endif /* TELNET_INTERFACE_H */
diff --git a/include/osmocom/vty/vty.h b/include/osmocom/vty/vty.h
index 8035585d..d1f6f440 100644
--- a/include/osmocom/vty/vty.h
+++ b/include/osmocom/vty/vty.h
@@ -4,6 +4,11 @@
 #include <stdio.h>
 #include <stdarg.h>
 
+/*! \defgroup vty VTY (Virtual TTY) interface
+ *  @{
+ */
+/*! \file vty.h */
+
 /* GCC have printf type attribute check.  */
 #ifdef __GNUC__
 #define VTY_PRINTF_ATTRIBUTE(a,b) __attribute__ ((__format__ (__printf__, a, b)))
@@ -21,7 +26,7 @@
 #define VTY_BUFSIZ 512
 #define VTY_MAXHIST 20
 
-/* Vty events */
+/*! \brief VTY events */
 enum event {
 	VTY_SERV,
 	VTY_READ,
@@ -35,87 +40,94 @@ enum event {
 #endif				/* VTYSH */
 };
 
+/*! Internal representation of a single VTY */
 struct vty {
+	/*! \brief underlying file (if any) */
 	FILE *file;
 
-	/* private data, specified by creator */
+	/*! \brief private data, specified by creator */
 	void *priv;
 
-	/* File descripter of this vty. */
+	/*! \brief File descripter of this vty. */
 	int fd;
 
-	/* Is this vty connect to file or not */
+	/*! \brief Is this vty connect to file or not */
 	enum { VTY_TERM, VTY_FILE, VTY_SHELL, VTY_SHELL_SERV } type;
 
-	/* Node status of this vty */
+	/*! \brief Node status of this vty */
 	int node;
 
-	/* Failure count */
+	/*! \brief Failure count */
 	int fail;
 
-	/* Output buffer. */
+	/*! \brief Output buffer. */
 	struct buffer *obuf;
 
-	/* Command input buffer */
+	/*! \brief Command input buffer */
 	char *buf;
 
-	/* Command cursor point */
+	/*! \brief Command cursor point */
 	int cp;
 
-	/* Command length */
+	/*! \brief Command length */
 	int length;
 
-	/* Command max length. */
+	/*! \brief Command max length. */
 	int max;
 
-	/* Histry of command */
+	/*! \brief Histry of command */
 	char *hist[VTY_MAXHIST];
 
-	/* History lookup current point */
+	/*! \brief History lookup current point */
 	int hp;
 
-	/* History insert end point */
+	/*! \brief History insert end point */
 	int hindex;
 
-	/* For current referencing point of interface, route-map,
+	/*! \brief For current referencing point of interface, route-map,
 	   access-list etc... */
 	void *index;
 
-	/* For multiple level index treatment such as key chain and key. */
+	/*! \brief For multiple level index treatment such as key chain and key. */
 	void *index_sub;
 
-	/* For escape character. */
+	/*! \brief For escape character. */
 	unsigned char escape;
 
-	/* Current vty status. */
+	/*! \brief Current vty status. */
 	enum { VTY_NORMAL, VTY_CLOSE, VTY_MORE, VTY_MORELINE } status;
 
-	/* IAC handling: was the last character received the IAC
+	/*! \brief IAC handling
+	 *
+	 * IAC handling: was the last character received the IAC
 	 * (interpret-as-command) escape character (and therefore the next
 	 * character will be the command code)?  Refer to Telnet RFC 854. */
 	unsigned char iac;
 
-	/* IAC SB (option subnegotiation) handling */
+	/*! \brief IAC SB (option subnegotiation) handling */
 	unsigned char iac_sb_in_progress;
 	/* At the moment, we care only about the NAWS (window size) negotiation,
 	 * and that requires just a 5-character buffer (RFC 1073):
 	 * <NAWS char> <16-bit width> <16-bit height> */
 #define TELNET_NAWS_SB_LEN 5
+	/*! \brief sub-negotiation buffer */
 	unsigned char sb_buf[TELNET_NAWS_SB_LEN];
-	/* How many subnegotiation characters have we received?  We just drop
-	 * those that do not fit in the buffer. */
+	/*! \brief How many subnegotiation characters have we received?  
+	 *
+	 * We just drop those that do not fit in the buffer. */
 	size_t sb_len;
 
-	/* Window width/height. */
+	/*! \brief Window width */
 	int width;
+	/*! \brief Widnow height */
 	int height;
 
-	/* Configure lines. */
+	/*! \brief Configure lines. */
 	int lines;
 
 	int monitor;
 
-	/* In configure mode. */
+	/*! \brief In configure mode. */
 	int config;
 };
 
@@ -127,12 +139,19 @@ static inline char *vty_newline(struct vty *vty)
 	return VTY_NEWLINE;
 }
 
+/*! Information an application registers with the VTY */
 struct vty_app_info {
+	/*! \brief name of the application */
 	const char *name;
+	/*! \brief version string of the application */
 	const char *version;
+	/*! \brief copyright string of the application */
 	const char *copyright;
+	/*! \brief \ref talloc context */
 	void *tall_ctx;
+	/*! \brief call-back for returning to parent n ode */
 	enum node_type (*go_parent_cb)(struct vty *vty);
+	/*! \brief call-back to determine if node is config node */
 	int (*is_config_node)(struct vty *vty, int node);
 };
 
@@ -159,4 +178,7 @@ void *vty_current_index(struct vty *);
 int vty_current_node(struct vty *vty);
 
 extern void *tall_vty_ctx;
+
+/*! }@ */
+
 #endif