# HG changeset patch
# User Myhailo Danylenko <isbear@ukrpost.net>
# Date 1234622409 -7200
# Node ID 5770be2d5f3fdc00cc4c9b028dc5f99b34c1704c
# Parent  4fd19a188509abdcda6485d5121e89b05de7b82a
Documentation updates

diff -r 4fd19a188509 -r 5770be2d5f3f docgen.pl
--- a/docgen.pl	Mon Feb 09 13:39:36 2009 +0200
+++ b/docgen.pl	Sat Feb 14 16:40:09 2009 +0200
@@ -6,6 +6,8 @@
 my %docs;
 my @tags;
 my $inside;
+my $harvest;
+my @values;
 
 foreach my $file (@ARGV) {
 	if ( not open SOURCE, '<', $file ) {
@@ -20,9 +22,21 @@
 			if ( not /^\/\/\// ) {
 				$inside = 0;
 				$chunk++;
+			} elsif ( /^\/\/\/ G:/ ) {
+				$inside = 0;
+				$harvest = 'V: ' . substr ( $_, 6 );
 			} else {
 				push @{$docs{$file}[$chunk]}, substr ( $_, 4 );
 			}
+		} elsif ( $harvest ) {
+			if ( /\{\s*NULL.*\}/ ) {
+				push @{$docs{$file}[$chunk]}, $harvest . ' ' . join ( ', ', @values );
+				$harvest = undef;
+				@values  = ();
+				$chunk++;
+			} elsif ( /\{\s*"(.+)".*\}/ ) {
+				push @values, $1;
+			}
 		} else {
 			next if not /^\/\/\//;
 
@@ -57,12 +71,24 @@
 	foreach my $chunk ( @{$docs{$file}} ) {
 		my $head = shift @$chunk;
 		my $tag  = $head;
+		my $list = undef;
 		$tag =~ s/_/./g;
 		print "<a name='$tag'></a><h2>$head</h2><p>";
 		foreach ( @$chunk ) {
 			s/^A: /<br\/>Arguments: /;
 			s/^R: /<br\/>Return values: /;
 			s/^V: /<br\/>Values: /;
+			if ( $list ) {
+				if ( /^\* / ) {
+					s/^\* /<\/li><li>/;
+				} else {
+					s/^/<\/li><\/ul> /;
+					$list = undef;
+				}
+			} elsif ( /^\* / ) {
+				s/^\* /<ul><li>/;
+				$list = 1;
+			}
 			foreach my $tag ( @tags ) {
 				# TODO quotemeta required, but for now
 				# this bug is rather desired...
@@ -71,6 +97,7 @@
 			}
 			print $_;
 		}
+		print "</li></ul>" if $list;
 		print "</p>"
 	}
 	print "<hr>";
diff -r 4fd19a188509 -r 5770be2d5f3f lm_connection.c
--- a/lm_connection.c	Mon Feb 09 13:39:36 2009 +0200
+++ b/lm_connection.c	Sat Feb 14 16:40:09 2009 +0200
@@ -16,7 +16,7 @@
 
 /// connection state
 /// Stirng, representing current connection state.
-/// V: closed, opening, open, authenticating, authenticated
+/// G:
 const string2enum_t llm_connection_state[] = {
 	{ "closed",         LM_CONNECTION_STATE_CLOSED         },
 	{ "opening",        LM_CONNECTION_STATE_OPENING        },
@@ -29,7 +29,7 @@
 /// handler priority
 /// String, according to which handler will be placed into one
 /// of three handler groups.
-/// V: last, normal, first
+/// G:
 const string2enum_t llm_handler_priority[] = {
 	{ "last",   LM_HANDLER_PRIORITY_LAST   },
 	{ "normal", LM_HANDLER_PRIORITY_NORMAL },
@@ -39,8 +39,8 @@
 
 /// disconnect reason
 /// String, indicating the reason of disconnection occured.
-/// V: ok, ping time out, hup, error, resource conflict, invalid xml, unknown, ping_time_out, resource_conflict, invalid_xml
-const string2enum_t llm_disconnect_reason[] = {
+/// G:
+static const string2enum_t llm_disconnect_reason[] = {
 	{ "ok",                LM_DISCONNECT_REASON_OK                },
 	{ "ping time out",     LM_DISCONNECT_REASON_PING_TIME_OUT     },
 	{ "hup",               LM_DISCONNECT_REASON_HUP               },
diff -r 4fd19a188509 -r 5770be2d5f3f lm_message.c
--- a/lm_message.c	Mon Feb 09 13:39:36 2009 +0200
+++ b/lm_message.c	Sat Feb 14 16:40:09 2009 +0200
@@ -12,7 +12,7 @@
 
 /// message type
 /// Message type (root tag type).
-/// V: message, presence, iq, stream, stream error, stream features, auth, challenge, response, success, failure, proceed, starttls, unknown, stream:stream, stream:error, stream:feature
+/// G:
 const string2enum_t llm_message_type[] = {
 	{ "message",         LM_MESSAGE_TYPE_MESSAGE         },
 	{ "presence",        LM_MESSAGE_TYPE_PRESENCE        },
@@ -36,7 +36,7 @@
 
 /// message sub type
 /// Message subtype, not all combinations of type and subtype are possible.
-/// V: not set, available, normal, chat, groupchat, headline, unavailable, probe, subscribe, unsubscribe, subscribed, unsubscribed, get, set, result, error, not_set
+/// G:
 const string2enum_t llm_message_sub_type[] = {
 	{ "not set",       LM_MESSAGE_SUB_TYPE_NOT_SET      },
 	{ "available",     LM_MESSAGE_SUB_TYPE_AVAILABLE    },
diff -r 4fd19a188509 -r 5770be2d5f3f lm_proxy.c
--- a/lm_proxy.c	Mon Feb 09 13:39:36 2009 +0200
+++ b/lm_proxy.c	Sat Feb 14 16:40:09 2009 +0200
@@ -14,7 +14,7 @@
 
 /// proxy type
 /// Stirng, specifying proxy-server type. The only type supported for now is http.
-/// V: http, none
+/// G:
 const string2enum_t llm_proxy_type[] = {
 	{ "http", LM_PROXY_TYPE_HTTP },
 	{ "none", LM_PROXY_TYPE_NONE },
diff -r 4fd19a188509 -r 5770be2d5f3f lm_ssl.c
--- a/lm_ssl.c	Mon Feb 09 13:39:36 2009 +0200
+++ b/lm_ssl.c	Sat Feb 14 16:40:09 2009 +0200
@@ -14,7 +14,7 @@
 
 /// ssl status
 /// String, representing what problem have current ssl session.
-/// V: no cert found, untrusted cert, cert expired, cert not activated, cert hostname mismatch, cert fingerprint mismatch, generic error
+/// G:
 const string2enum_t llm_ssl_status[] = {
 	{ "no cert found",             LM_SSL_STATUS_NO_CERT_FOUND             },
 	{ "untrusted cert",            LM_SSL_STATUS_UNTRUSTED_CERT            },
diff -r 4fd19a188509 -r 5770be2d5f3f util.c
--- a/util.c	Mon Feb 09 13:39:36 2009 +0200
+++ b/util.c	Sat Feb 14 16:40:09 2009 +0200
@@ -25,6 +25,9 @@
 	return NULL;
 }
 
+/// argument enum field
+/// String that will be converted to number or just plain number, that will be passed as is.
+/// Note, that if enum name is not recognized no error will be raised and default vale will be used.
 enum_value_t luaL_checkenum (lua_State *L, int index, const string2enum_t *set)
 {
 	if (lua_type (L, index) == LUA_TNUMBER)
@@ -33,6 +36,8 @@
 		return string2enum (luaL_checkstring (L, index), set);
 }
 
+/// return enum field
+/// String. If no string found, plain number will be returned.
 void luaL_pushenum (lua_State *L, enum_value_t value, const string2enum_t *set)
 {
 	const char *string = enum2string (value, set);
@@ -42,6 +47,12 @@
 		lua_pushinteger (L, value);
 }
 
+/// argument flags field
+/// Can be just plain number, then it is passed as is.
+/// Can be a string, then it is recognized as a single enabled flag.
+/// Or can be a table of the following format:
+/// * integer keys should have string values, that will be used as enabled flag names or numerical values, that will be just ORed;
+/// * string keys should be flag names, that will be enabled, if corresponding value contains true value.
 enum_value_t luaL_checkenum_multi (lua_State *L, int index, const string2enum_t *set)
 {
 	int type = lua_type (L, index);
@@ -74,6 +85,10 @@
 	return 0; // never happens
 }
 
+/// returned flags field
+/// Is always a table with present flag names as keys with true values.
+/// Not present flags are not present in table either.
+/// Not recognized values, if present, will be stored as a number in a first sequential table member (table[1]).
 void luaL_pushenum_multi (lua_State *L, enum_value_t value, const string2enum_t *set)
 {
 	enum_value_t matched = 0;
diff -r 4fd19a188509 -r 5770be2d5f3f util.h
--- a/util.h	Mon Feb 09 13:39:36 2009 +0200
+++ b/util.h	Sat Feb 14 16:40:09 2009 +0200
@@ -4,6 +4,7 @@
 
 #include <lua.h>
 
+// You can set this if anther type is required
 #ifndef enum_value_t
 #define enum_value_t int
 #endif