[asterisk-commits] mnicholson: branch mnicholson/asttest r191094 - /team/mnicholson/asttest/astt...

[SVN commits to the Asterisk project]

Author: mnicholson
Date: Wed Apr 29 12:02:39 2009
New Revision: 191094

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=191094
Log:
Added some documetation for functions in astlib.c

Modified:
    team/mnicholson/asttest/asttest/lua/astlib.c

Modified: team/mnicholson/asttest/asttest/lua/astlib.c
URL: http://svn.digium.com/svn-view/asterisk/team/mnicholson/asttest/asttest/lua/astlib.c?view=diff&rev=191094&r1=191093&r2=191094
==============================================================================
--- team/mnicholson/asttest/asttest/lua/astlib.c (original)
+++ team/mnicholson/asttest/asttest/lua/astlib.c Wed Apr 29 12:02:39 2009
@@ -190,6 +190,16 @@
 	return 0;
 }
 
+/*!
+ * \brief [lua_CFunction asterisk:_new] Partially create an instance of the
+ * asterisk object.
+ * \param L the lua state to use
+ *
+ * This function creates and partially initilizes an instance of the asterisk
+ * object.  It also increments the global asterisk instance index.
+ *
+ * \return new instance of the asterisk object
+ */
 static int new_asterisk(lua_State *L) {
 	int asterisk_count;
 
@@ -220,6 +230,14 @@
 	return 1;
 }
 
+/*!
+ * \brief [lua_CFunction asterisk:_clean_work_area] Clean up the work area for
+ * this instance.
+ * \param L the lua state to use
+ *
+ * This function cleans up the work area for this instance by deleting the work
+ * area directory if it exists.
+ */
 static int clean_work_area(lua_State *L) {
 	const char *work_area;
 	luaL_checktype(L, 1, LUA_TTABLE);
@@ -237,6 +255,13 @@
 	return 0;
 }
 
+/*!
+ * \brief [lua_CFunction asterisk:_create_work_area] Create the work area.
+ * \param L the lua state to use
+ *
+ * This function copies and symlinks files from the asterisk path to prepare
+ * the work area for this instance.
+ */
 static int create_work_area(lua_State *L) {
 	const char *work_area;
 	const char *asterisk_path;
@@ -277,6 +302,12 @@
 	return 0;
 }
 
+/*!
+ * \brief [lua_CFunction asterisk:_spawn] Start asterisk.
+ * \param L the lua state to use
+ *
+ * This function forks and execs asterisk.
+ */
 static int spawn_asterisk(lua_State *L) {
 	const char *asterisk;
 	const char *asterisk_conf;
@@ -320,6 +351,13 @@
 	return 0;
 }
 
+/*!
+ * \brief [lua_CFunction astlib_pid:__gc] Kill asterisk.
+ * \param L the lua state to use
+ *
+ * This is the gc function for the pid userdata.  This function will send a
+ * TERM signal to asterisk and then run waitpid.
+ */
 static int pid_gc(lua_State *L) {
 	pid_t *p = luaL_checkudata(L, 1, "astlib_pid");
 	if (kill(*p, SIGTERM)) {
@@ -333,6 +371,16 @@
 	return 0;
 }
 
+/*!
+ * \brief [lua_CFunction asterisk:wait] Wait for the asterisk process to end.
+ * \param L the lua state to use
+ *
+ * This function calls waitpid on the running asterisk process.
+ *
+ * \return a tuple containg the exit code, nil and the signal that caused
+ * asterisk to exit, or nil and a string describing the error ("error" or
+ * "core" currently).
+ */
 static int wait_asterisk(lua_State *L) {
 	pid_t pid;
 	int status;
@@ -374,6 +422,16 @@
 	return 2;
 }
 
+/*!
+ * \brief [lua_CFunction asterisk:kill] Kill asterisk with SIGKILL.
+ * \param L the lua state to use
+ *
+ * This function sends asterisk SIGKILL then calls asterisk:wait() and returns
+ * the result.
+ *
+ * \return same as wait_asterisk() and in the case of "error" an additional
+ * error description and errno may be returned
+ */
 static int kill_asterisk(lua_State *L) {
 	pid_t pid;
 
@@ -404,6 +462,16 @@
 	return 2;
 }
 
+/*!
+ * \brief [lua_CFunction asterisk:term] Terminate asterisk with SIGTERM.
+ * \param L the lua state to use
+ *
+ * This function sends asterisk SIGTERM then calls asterisk:wait() and returns
+ * the result.
+ *
+ * \return same as wait_asterisk() and in the case of "error" an additional
+ * error description and errno may be returned
+ */
 static int terminate_asterisk(lua_State *L) {
 	pid_t pid;
 
@@ -434,6 +502,13 @@
 	return 2;
 }
 
+/*!
+ * \brief [lua_CFunction ast:unlink] Unlink the given file.
+ * \param L the lua state to use
+ *
+ * \retval -1 error
+ * \retval 0 success
+ */
 static int unlink_file(lua_State *L) {
 	const char *file = luaL_checkstring(L, 1);
 	lua_pushinteger(L, unlink(file));