From be67fdd00ab2bb00bc6c7e5be8660909662d36e2 Mon Sep 17 00:00:00 2001 From: mid Date: Wed, 8 Nov 2000 10:29:02 +0000 Subject: [PATCH] - Wed Nov 8 02:23:25 UTC 2000 - I'm trying out using a modified version of the kernel-doc scripts to help document the libfaim code a bit. See aim_conn.c and aim_tlv.c, as well as the scripts in utils/docs. --- CHANGES | 5 + aim_conn.c | 164 ++++++- aim_tlv.c | 246 +++++++++- utils/docs/libfaim-doc.pl | 949 ++++++++++++++++++++++++++++++++++++++ utils/docs/split-man.pl | 23 + 5 files changed, 1346 insertions(+), 41 deletions(-) create mode 100755 utils/docs/libfaim-doc.pl create mode 100755 utils/docs/split-man.pl diff --git a/CHANGES b/CHANGES index c167655..008ebaf 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,11 @@ No release numbers ------------------ + - Wed Nov 8 02:23:25 UTC 2000 + - I'm trying out using a modified version of the kernel-doc scripts + to help document the libfaim code a bit. See aim_conn.c and + aim_tlv.c, as well as the scripts in utils/docs. + - Wed Oct 25 17:52:20 UTC 2000 - Cleanup warnings from newer gcc's (RH7.0) - Aparently newer gcc's don't let you do as strong of integer types diff --git a/aim_conn.c b/aim_conn.c index 8c91d18..5009627 100644 --- a/aim_conn.c +++ b/aim_conn.c @@ -14,8 +14,12 @@ #include #endif -/* - * Clears out connection list, killing remaining connections. +/** + * aim_connrst - Clears out connection list, killing remaining connections. + * @sess: Session to be cleared + * + * Clears out the connection list and kills any connections left. + * */ faim_internal void aim_connrst(struct aim_session_t *sess) { @@ -34,8 +38,12 @@ faim_internal void aim_connrst(struct aim_session_t *sess) return; } -/* - * Gets a new connection structure. +/** + * aim_conn_getnext - Gets a new connection structure. + * @sess: Session + * + * Allocate a new empty connection structure. + * */ faim_internal struct aim_conn_t *aim_conn_getnext(struct aim_session_t *sess) { @@ -61,6 +69,13 @@ faim_internal struct aim_conn_t *aim_conn_getnext(struct aim_session_t *sess) return newconn; } +/** + * aim_conn_init - Reset a connection to default values. + * @deadconn: Connection to be reset + * + * Initializes and/or resets a connection structure. + * + */ static void aim_conn_init(struct aim_conn_t *deadconn) { if (!deadconn) @@ -80,6 +95,14 @@ static void aim_conn_init(struct aim_conn_t *deadconn) return; } +/** + * aim_conn_kill - Close and free a connection. + * @sess: Session for the connection + * @deadconn: Connection to be freed + * + * Close, clear, and free a connection structure. + * + */ faim_export void aim_conn_kill(struct aim_session_t *sess, struct aim_conn_t **deadconn) { struct aim_conn_t *cur; @@ -117,6 +140,13 @@ faim_export void aim_conn_kill(struct aim_session_t *sess, struct aim_conn_t **d return; } +/** + * aim_conn_close - Close a connection + * @deadconn: Connection to close + * + * Close (but not free) a connection. + * + */ faim_export void aim_conn_close(struct aim_conn_t *deadconn) { int typesav = -1, subtypesav = -1; @@ -147,6 +177,16 @@ faim_export void aim_conn_close(struct aim_conn_t *deadconn) return; } +/** + * aim_getconn_type - Find a connection of a specific type + * @sess: Session to search + * @type: Type of connection to look for + * + * Searches for a connection of the specified type in the + * specified session. Returns the first connection of that + * type found. + * + */ faim_internal struct aim_conn_t *aim_getconn_type(struct aim_session_t *sess, int type) { @@ -161,8 +201,17 @@ faim_internal struct aim_conn_t *aim_getconn_type(struct aim_session_t *sess, return cur; } -/* - * An extrememly quick and dirty SOCKS5 interface. +/** + * aim_proxyconnect - An extrememly quick and dirty SOCKS5 interface. + * @sess: Session to connect + * @host: Host to connect to + * @port: Port to connect to + * @statusret: Return value of the connection + * + * Attempts to connect to the specified host via the configured + * proxy settings, if present. If no proxy is configured for + * this session, the connection is done directly. + * */ static int aim_proxyconnect(struct aim_session_t *sess, char *host, unsigned short port, @@ -309,10 +358,16 @@ static int aim_proxyconnect(struct aim_session_t *sess, return fd; } -/* - * aim_newconn(type, dest) +/** + * aim_newconn - Open a new connection + * @sess: Session to create connection in + * @type: Type of connection to create + * @dest: Host to connect to (in "host:port" syntax) * - * Opens a new connection to the specified dest host of type type. + * Opens a new connection to the specified dest host of specified + * type, using the proxy settings if available. If @host is %NULL, + * the connection is allocated and returned, but no connection + * is made. * * FIXME: Return errors in a more sane way. * @@ -375,6 +430,14 @@ faim_export struct aim_conn_t *aim_newconn(struct aim_session_t *sess, return connstruct; } +/** + * aim_conngetmaxfd - Return the highest valued file discriptor in session + * @sess: Session to search + * + * Returns the highest valued filed descriptor of all open + * connections in @sess. + * + */ faim_export int aim_conngetmaxfd(struct aim_session_t *sess) { int j = 0; @@ -390,6 +453,13 @@ faim_export int aim_conngetmaxfd(struct aim_session_t *sess) return j; } +/** + * aim_countconn - Return the number of open connections in the session + * @sess: Session to look at + * + * Returns the number of number connections in @sess. + * + */ static int aim_countconn(struct aim_session_t *sess) { int cnt = 0; @@ -403,6 +473,15 @@ static int aim_countconn(struct aim_session_t *sess) return cnt; } +/** + * aim_conn_in_sess - Predicate to test the precense of a connection in a sess + * @sess: Session to look in + * @conn: Connection to look for + * + * Searches @sess for the passed connection. Returns 1 if its present, + * zero otherwise. + * + */ faim_export int aim_conn_in_sess(struct aim_session_t *sess, struct aim_conn_t *conn) { struct aim_conn_t *cur; @@ -417,16 +496,19 @@ faim_export int aim_conn_in_sess(struct aim_session_t *sess, struct aim_conn_t * return 0; } -/* - * aim_select(timeout) +/** + * aim_select - Wait for a socket with data or timeout + * @sess: Session to wait on + * @timeout: How long to wait + * @status: Return status * * Waits for a socket with data or for timeout, whichever comes first. - * See select(2). + * See select(). * * Return codes in *status: - * -1 error in select() (NULL returned) - * 0 no events pending (NULL returned) - * 1 outgoing data pending (NULL returned) + * -1 error in select() (%NULL returned) + * 0 no events pending (%NULL returned) + * 1 outgoing data pending (%NULL returned) * 2 incoming data pending (connection with pending data returned) * * XXX: we could probably stand to do a little courser locking here. @@ -486,6 +568,16 @@ faim_export struct aim_conn_t *aim_select(struct aim_session_t *sess, return NULL; /* no waiting or error, return */ } +/** + * aim_conn_isready - Test if a connection is marked ready + * @conn: Connection to test + * + * Returns true if the connection is ready, false otherwise. + * Returns -1 if the connection is invalid. + * + * XXX: This is deprecated. + * + */ faim_export int aim_conn_isready(struct aim_conn_t *conn) { if (conn) @@ -493,6 +585,15 @@ faim_export int aim_conn_isready(struct aim_conn_t *conn) return -1; } +/** + * aim_conn_setstatus - Set the status of a connection + * @conn: Connection + * @status: New status + * + * @newstatus is %XOR'd with the previous value of the connection + * status and returned. Returns -1 if the connection is invalid. + * + */ faim_export int aim_conn_setstatus(struct aim_conn_t *conn, int status) { int val; @@ -506,6 +607,20 @@ faim_export int aim_conn_setstatus(struct aim_conn_t *conn, int status) return val; } +/** + * aim_conn_setlatency - Set a forced latency value for connection + * @conn: Conn to set latency for + * @newval: Number of seconds to force between transmits + * + * Causes @newval seconds to be spent between transmits on a connection. + * + * This is my lame attempt at overcoming not understanding the rate + * limiting. + * + * XXX: This should really be replaced with something that scales and + * backs off like the real rate limiting does. + * + */ faim_export int aim_conn_setlatency(struct aim_conn_t *conn, int newval) { if (!conn) @@ -519,12 +634,18 @@ faim_export int aim_conn_setlatency(struct aim_conn_t *conn, int newval) return 0; } -/* +/** + * aim_setupproxy - Configure a proxy for this session + * @sess: Session to set proxy for + * @server: SOCKS server + * @username: SOCKS username + * @password: SOCKS password + * * Call this with your SOCKS5 proxy server parameters before - * the first call to aim_newconn(). If called with all NULL + * the first call to aim_newconn(). If called with all %NULL * args, it will clear out a previously set proxy. * - * Set username and password to NULL if not applicable. + * Set username and password to %NULL if not applicable. * */ faim_export void aim_setupproxy(struct aim_session_t *sess, char *server, char *username, char *password) @@ -545,6 +666,13 @@ faim_export void aim_setupproxy(struct aim_session_t *sess, char *server, char * return; } +/** + * aim_session_init - Initializes a session structure + * @sess: Session to initialize + * + * Sets up the initial values for a session. + * + */ faim_export void aim_session_init(struct aim_session_t *sess) { if (!sess) diff --git a/aim_tlv.c b/aim_tlv.c index 75cc7ea..b5f69a0 100644 --- a/aim_tlv.c +++ b/aim_tlv.c @@ -1,6 +1,17 @@ #include -faim_internal struct aim_tlvlist_t *aim_readtlvchain(u_char *buf, int maxlen) +/** + * aim_readtlvchain - Read a TLV chain from a buffer. + * @buf: Input buffer + * @maxlen: Length of input buffer + * + * Reads and parses a series of TLV patterns from a data buffer; the + * returned structure is manipulatable with the rest of the TLV + * routines. When done with a TLV chain, aim_freetlvchain() should + * be called to free the dynamic substructures. + * + */ +faim_export struct aim_tlvlist_t *aim_readtlvchain(u_char *buf, int maxlen) { int pos; struct aim_tlvlist_t *list; @@ -62,7 +73,16 @@ faim_internal struct aim_tlvlist_t *aim_readtlvchain(u_char *buf, int maxlen) return list; } -faim_internal void aim_freetlvchain(struct aim_tlvlist_t **list) +/** + * aim_freetlvchain - Free a TLV chain structure + * @list: Chain to be freed + * + * Walks the list of TLVs in the passed TLV chain and + * frees each one. Note that any references to this data + * should be removed before calling this. + * + */ +faim_export void aim_freetlvchain(struct aim_tlvlist_t **list) { struct aim_tlvlist_t *cur, *cur2; @@ -81,7 +101,14 @@ faim_internal void aim_freetlvchain(struct aim_tlvlist_t **list) return; } -faim_internal int aim_counttlvchain(struct aim_tlvlist_t **list) +/** + * aim_counttlvchain - Count the number of TLVs in a chain + * @list: Chain to be counted + * + * Returns the number of TLVs stored in the passed chain. + * + */ +faim_export int aim_counttlvchain(struct aim_tlvlist_t **list) { struct aim_tlvlist_t *cur; int count = 0; @@ -95,6 +122,14 @@ faim_internal int aim_counttlvchain(struct aim_tlvlist_t **list) return count; } +/** + * aim_sizetlvchain - Count the number of bytes in a TLV chain + * @list: Chain to be sized + * + * Returns the number of bytes that would be needed to + * write the passed TLV chain to a data buffer. + * + */ faim_export int aim_sizetlvchain(struct aim_tlvlist_t **list) { struct aim_tlvlist_t *cur; @@ -109,8 +144,18 @@ faim_export int aim_sizetlvchain(struct aim_tlvlist_t **list) return size; } - -faim_internal int aim_addtlvtochain_str(struct aim_tlvlist_t **list, unsigned short type, char *str, int len) +/** + * aim_addtlvtochain_str - Add a string to a TLV chain + * @list: Desination chain (%NULL pointer if empty) + * @type: TLV type + * @str: String to add + * @len: Length of string to add (not including %NULL) + * + * Adds the passed string as a TLV element of the passed type + * to the TLV chain. + * + */ +faim_export int aim_addtlvtochain_str(struct aim_tlvlist_t **list, unsigned short type, char *str, int len) { struct aim_tlvlist_t *newtlv; struct aim_tlvlist_t *cur; @@ -141,7 +186,16 @@ faim_internal int aim_addtlvtochain_str(struct aim_tlvlist_t **list, unsigned sh return newtlv->tlv->length; } -faim_internal int aim_addtlvtochain16(struct aim_tlvlist_t **list, unsigned short type, unsigned short val) +/** + * aim_addtlvtochain16 - Add a 16bit integer to a TLV chain + * @list: Destination chain + * @type: TLV type to add + * @val: Value to add + * + * Adds a two-byte unsigned integer to a TLV chain. + * + */ +faim_export int aim_addtlvtochain16(struct aim_tlvlist_t **list, unsigned short type, unsigned short val) { struct aim_tlvlist_t *newtl; struct aim_tlvlist_t *cur; @@ -172,7 +226,16 @@ faim_internal int aim_addtlvtochain16(struct aim_tlvlist_t **list, unsigned shor return 2; } -faim_internal int aim_addtlvtochain32(struct aim_tlvlist_t **list, unsigned short type, unsigned long val) +/** + * aim_addtlvtochain32 - Add a 32bit integer to a TLV chain + * @list: Destination chain + * @type: TLV type to add + * @val: Value to add + * + * Adds a four-byte unsigned integer to a TLV chain. + * + */ +faim_export int aim_addtlvtochain32(struct aim_tlvlist_t **list, unsigned short type, unsigned long val) { struct aim_tlvlist_t *newtl; struct aim_tlvlist_t *cur; @@ -203,7 +266,29 @@ faim_internal int aim_addtlvtochain32(struct aim_tlvlist_t **list, unsigned shor return 4; } -faim_internal int aim_addtlvtochain_caps(struct aim_tlvlist_t **list, unsigned short type, unsigned short caps) +/** + * aim_addtlvtochain_caps - Add a capability block to a TLV chain + * @list: Destination chain + * @type: TLV type to add + * @caps: Bitfield of capability flags to send + * + * Adds a block of capability blocks to a TLV chain. The bitfield + * passed in should be a bitwise %OR of any of the %AIM_CAPS constants: + * + * %AIM_CAPS_BUDDYICON Supports Buddy Icons + * + * %AIM_CAPS_VOICE Supports Voice Chat + * + * %AIM_CAPS_IMIMAGE Supports DirectIM/IMImage + * + * %AIM_CAPS_CHAT Supports Chat + * + * %AIM_CAPS_GETFILE Supports Get File functions + * + * %AIM_CAPS_SENDFILE Supports Send File functions + * + */ +faim_export int aim_addtlvtochain_caps(struct aim_tlvlist_t **list, unsigned short type, unsigned short caps) { unsigned char buf[128]; /* icky fixed length buffer */ struct aim_tlvlist_t *newtl; @@ -236,7 +321,19 @@ faim_internal int aim_addtlvtochain_caps(struct aim_tlvlist_t **list, unsigned s return newtl->tlv->length; } -faim_internal int aim_writetlvchain(u_char *buf, int buflen, struct aim_tlvlist_t **list) +/** + * aim_writetlvchain - Write a TLV chain into a data buffer. + * @buf: Destination buffer + * @buflen: Maximum number of bytes that will be written to buffer + * @list: Source TLV chain + * + * Copies a TLV chain into a raw data buffer, writing only the number + * of bytes specified. This operation does not free the chain; + * aim_freetlvchain() must still be called to free up the memory used + * by the chain structures. + * + */ +faim_export int aim_writetlvchain(u_char *buf, int buflen, struct aim_tlvlist_t **list) { int goodbuflen = 0; int i = 0; @@ -266,10 +363,19 @@ faim_internal int aim_writetlvchain(u_char *buf, int buflen, struct aim_tlvlist_ } -/* - * Grab the Nth TLV of type type in the TLV list list. +/** + * aim_gettlv - Grab the Nth TLV of type type in the TLV list list. + * @list: Source chain + * @type: Requested TLV type + * @nth: Index of TLV of type to get + * + * Returns a pointer to an aim_tlv_t of the specified type; + * %NULL on error. The @nth parameter is specified starting at %1. + * In most cases, there will be no more than one TLV of any type + * in a chain. + * */ -faim_internal struct aim_tlv_t *aim_gettlv(struct aim_tlvlist_t *list, u_short type, int nth) +faim_export struct aim_tlv_t *aim_gettlv(struct aim_tlvlist_t *list, u_short type, int nth) { int i; struct aim_tlvlist_t *cur; @@ -288,7 +394,18 @@ faim_internal struct aim_tlv_t *aim_gettlv(struct aim_tlvlist_t *list, u_short t return NULL; } -faim_internal char *aim_gettlv_str(struct aim_tlvlist_t *list, u_short type, int nth) +/** + * aim_gettlv_str - Retrieve the Nth TLV in chain as a string. + * @list: Source TLV chain + * @type: TLV type to search for + * @nth: Index of TLV to return + * + * Same as aim_gettlv(), except that the return value is a %NULL- + * terminated string instead of an aim_tlv_t. This is a + * dynamic buffer and must be freed by the caller. + * + */ +faim_export char *aim_gettlv_str(struct aim_tlvlist_t *list, u_short type, int nth) { struct aim_tlv_t *tlv; char *newstr; @@ -303,7 +420,19 @@ faim_internal char *aim_gettlv_str(struct aim_tlvlist_t *list, u_short type, int return newstr; } -faim_internal struct aim_tlv_t *aim_grabtlv(u_char *src) +/** + * aim_grabtlv - Grab a single TLV from a data buffer + * @src: Source data buffer (must be at least 4 bytes long) + * + * Creates a TLV structure aim_tlv_t and returns it + * filled with values from a buffer, possibly including a + * dynamically allocated buffer for the value portion. + * + * Both the aim_tlv_t and the tlv->value pointer + * must be freed by the caller if non-%NULL. + * + */ +faim_export struct aim_tlv_t *aim_grabtlv(u_char *src) { struct aim_tlv_t *dest = NULL; @@ -323,7 +452,20 @@ faim_internal struct aim_tlv_t *aim_grabtlv(u_char *src) return dest; } -faim_internal struct aim_tlv_t *aim_grabtlvstr(u_char *src) +/** + * aim_grabtlvstr - Grab a single TLV from a data buffer as string + * @src: Source data buffer (must be at least 4 bytes long) + * + * Creates a TLV structure aim_tlv_t and returns it + * filled with values from a buffer, possibly including a + * dynamically allocated buffer for the value portion, which + * is %NULL-terminated as a string. + * + * Both the aim_tlv_t and the tlv->value pointer + * must be freed by the caller if non-%NULL. + * + */ +faim_export struct aim_tlv_t *aim_grabtlvstr(u_char *src) { struct aim_tlv_t *dest = NULL; @@ -344,7 +486,19 @@ faim_internal struct aim_tlv_t *aim_grabtlvstr(u_char *src) return dest; } -faim_internal int aim_puttlv(u_char *dest, struct aim_tlv_t *newtlv) +/** + * aim_puttlv - Write a aim_tlv_t into a data buffer + * @dest: Destination data buffer + * @newtlv: Source TLV structure + * + * Writes out the passed TLV structure into the buffer. No bounds + * checking is done on the output buffer. + * + * The passed aim_tlv_t is not freed. aim_freetlv() should + * still be called by the caller to free the structure. + * + */ +faim_export int aim_puttlv(u_char *dest, struct aim_tlv_t *newtlv) { int i=0; @@ -357,15 +511,31 @@ faim_internal int aim_puttlv(u_char *dest, struct aim_tlv_t *newtlv) return i; } -faim_internal struct aim_tlv_t *aim_createtlv(void) +/** + * aim_createtlv - Generate an aim_tlv_t structure. + * + * Allocates an empty TLV structure and returns a pointer + * to it; %NULL on error. + * + */ +faim_export struct aim_tlv_t *aim_createtlv(void) { - struct aim_tlv_t *newtlv = NULL; - newtlv = (struct aim_tlv_t *)malloc(sizeof(struct aim_tlv_t)); + struct aim_tlv_t *newtlv; + + if (!(newtlv = (struct aim_tlv_t *)malloc(sizeof(struct aim_tlv_t)))) + return NULL; memset(newtlv, 0, sizeof(struct aim_tlv_t)); return newtlv; } -faim_internal int aim_freetlv(struct aim_tlv_t **oldtlv) +/** + * aim_freetlv - Free a aim_tlv_t structure + * @oldtlv: TLV to be destroyed + * + * Frees both the TLV structure and the value portion. + * + */ +faim_export int aim_freetlv(struct aim_tlv_t **oldtlv) { if (!oldtlv) return -1; @@ -379,7 +549,16 @@ faim_internal int aim_freetlv(struct aim_tlv_t **oldtlv) return 0; } -faim_internal int aim_puttlv_16(u_char *buf, u_short t, u_short v) +/** + * aim_puttlv_16 - Write a two-byte TLV. + * @buf: Destination buffer + * @t: TLV type + * @v: Value + * + * Writes a TLV with a two-byte integer value portion. + * + */ +faim_export int aim_puttlv_16(u_char *buf, u_short t, u_short v) { int curbyte=0; curbyte += aimutil_put16(buf+curbyte, (u_short)(t&0xffff)); @@ -388,7 +567,16 @@ faim_internal int aim_puttlv_16(u_char *buf, u_short t, u_short v) return curbyte; } -faim_internal int aim_puttlv_32(u_char *buf, u_short t, u_long v) +/** + * aim_puttlv_32 - Write a four-byte TLV. + * @buf: Destination buffer + * @t: TLV type + * @v: Value + * + * Writes a TLV with a four-byte integer value portion. + * + */ +faim_export int aim_puttlv_32(u_char *buf, u_short t, u_long v) { int curbyte=0; curbyte += aimutil_put16(buf+curbyte, (u_short)(t&0xffff)); @@ -397,7 +585,19 @@ faim_internal int aim_puttlv_32(u_char *buf, u_short t, u_long v) return curbyte; } -faim_internal int aim_puttlv_str(u_char *buf, u_short t, int l, char *v) +/** + * aim_puttlv_str - Write a string TLV. + * @buf: Destination buffer + * @t: TLV type + * @l: Length of string + * @v: String to write + * + * Writes a TLV with a string value portion. (Only the first @l + * bytes of the passed string will be written, which should not + * include the terminating NULL.) + * + */ +faim_export int aim_puttlv_str(u_char *buf, u_short t, int l, char *v) { int curbyte; diff --git a/utils/docs/libfaim-doc.pl b/utils/docs/libfaim-doc.pl new file mode 100755 index 0000000..c60c0ae --- /dev/null +++ b/utils/docs/libfaim-doc.pl @@ -0,0 +1,949 @@ +#!/usr/bin/perl + +## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## +## Copyright (C) 2000 Tim Waugh ## +## ## +## This software falls under the GNU General Public License. ## +## Please read the COPYING file for more information ## + +# +# This will read a 'c' file and scan for embedded comments in the +# style of gnome comments (+minor extensions - see below). +# + +# Note: This only supports 'c'. + +# usage: +# kerneldoc [ -docbook | -html | -text | -man ] +# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile +# or +# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile +# +# Set output format using one of -docbook -html -text or -man. Default is man. +# +# -function funcname +# If set, then only generate documentation for the given function(s). All +# other functions are ignored. +# +# -nofunction funcname +# If set, then only generate documentation for the other function(s). All +# other functions are ignored. Cannot be used with -function together +# (yes thats a bug - perl hackers can fix it 8)) +# +# c files - list of 'c' files to process +# +# All output goes to stdout, with errors to stderr. + +# +# format of comments. +# In the following table, (...)? signifies optional structure. +# (...)* signifies 0 or more structure elements +# /** +# * function_name(:)? (- short description)? +# (* @parameterx: (description of parameter x)?)* +# (* a blank line)? +# * (Description:)? (Description of function)? +# * (section header: (section description)? )* +# (*)?*/ +# +# So .. the trivial example would be: +# +# /** +# * my_function +# **/ +# +# If the Description: header tag is ommitted, then there must be a blank line +# after the last parameter specification. +# e.g. +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * +# * Does my stuff explained. +# */ +# +# or, could also use: +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * Description: Does my stuff explained. +# */ +# etc. +# +# All descriptions can be multiline, apart from the short function description. +# +# All descriptive text is further processed, scanning for the following special +# patterns, which are highlighted appropriately. +# +# 'funcname()' - function +# '$ENVVAR' - environmental variable +# '&struct_name' - name of a structure (up to two words including 'struct') +# '@parameter' - name of a parameter +# '%CONST' - name of a constant. + +# match expressions used to find embedded type information +$type_constant = "\\\%([-_\\w]+)"; +$type_func = "(\\w+)\\(\\)"; +$type_param = "\\\@(\\w+)"; +$type_struct = "\\\&((struct\\s*)?\\w+)"; +$type_env = "(\\\$\\w+)"; + + +# Output conversion substitutions. +# One for each output format + +# these work fairly well +%highlights_html = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +$blankline_html = "

"; + +# sgml, docbook format +%highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", + $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +$blankline_sgml = "\n"; + +# gnome, docbook format +%highlights_gnome = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +$blankline_gnome = "\n"; + +# these are pretty rough +%highlights_man = ( $type_constant, "\$1", + $type_func, "\\\\fB\$1\\\\fP", + $type_struct, "\\\\fI\$1\\\\fP", + $type_param, "\\\\fI\$1\\\\fP" ); +$blankline_man = ""; + +# text-mode +%highlights_text = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +$blankline_text = ""; + + +sub usage { + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n"; + print " [ -function funcname [ -function funcname ...] ]\n"; + print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; + print " c source file(s) > outputfile\n"; + exit 1; +} + +# read arguments +if ($#ARGV==-1) { + usage(); +} + +$verbose = 0; +$output_mode = "man"; +%highlights = %highlights_man; +$blankline = $blankline_man; +$modulename = "libfaim API Documentation"; +$function_only = 0; +while ($ARGV[0] =~ m/^-(.*)/) { + $cmd = shift @ARGV; + if ($cmd eq "-html") { + $output_mode = "html"; + %highlights = %highlights_html; + $blankline = $blankline_html; + } elsif ($cmd eq "-man") { + $output_mode = "man"; + %highlights = %highlights_man; + $blankline = $blankline_man; + } elsif ($cmd eq "-text") { + $output_mode = "text"; + %highlights = %highlights_text; + $blankline = $blankline_text; + } elsif ($cmd eq "-docbook") { + $output_mode = "sgml"; + %highlights = %highlights_sgml; + $blankline = $blankline_sgml; + } elsif ($cmd eq "-gnome") { + $output_mode = "gnome"; + %highlights = %highlights_gnome; + $blankline = $blankline_gnome; + } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document + $modulename = shift @ARGV; + } elsif ($cmd eq "-function") { # to only output specific functions + $function_only = 1; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "-nofunction") { # to only output specific functions + $function_only = 2; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "-v") { + $verbose = 1; + } elsif (($cmd eq "-h") || ($cmd eq "--help")) { + usage(); + } +} + + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +$dohighlight = ""; +foreach $pattern (keys %highlights) { +# print "scanning pattern $pattern ($highlights{$pattern})\n"; + $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; +} + +## +# dumps section contents to arrays/hashes intended for that purpose. +# +sub dump_section { + my $name = shift @_; + my $contents = join "\n", @_; + + if ($name =~ m/$type_constant/) { + $name = $1; +# print STDERR "constant section '$1' = '$contents'\n"; + $constants{$name} = $contents; + } elsif ($name =~ m/$type_param/) { +# print STDERR "parameter def '$1' = '$contents'\n"; + $name = $1; + $parameters{$name} = $contents; + } else { +# print STDERR "other section '$name' = '$contents'\n"; + $sections{$name} = $contents; + push @sectionlist, $name; + } +} + +## +# output function +# +# parameters, a hash. +# function => "function name" +# parameterlist => @list of parameters +# parameters => %parameter descriptions +# sectionlist => @list of sections +# sections => %descriont descriptions +# + +sub output_highlight { + my $contents = join "\n", @_; + my $line; + + eval $dohighlight; + foreach $line (split "\n", $contents) { + if ($line eq ""){ + print $lineprefix, $blankline; + } else { + $line =~ s/\\\\\\/\&/g; + print $lineprefix, $line; + } + print "\n"; + } +} + + +# output in html +sub output_html { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + print "

Function

\n"; + + print "".$args{'functiontype'}."\n"; + print "".$args{'function'}."\n"; + print "("; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "$1$parameter) ($2)"; + } else { + print "".$type." ".$parameter.""; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + } + print ")\n"; + + print "

Arguments

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameters'}{$parameter}); + } + print "
\n"; + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
\n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } + print "
\n"; +} + + +# output in html +sub output_intro_html { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
    \n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } + print "
\n"; +} + + + +# output in sgml DocBook +sub output_sgml { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print "".$args{'function'}."\n"; + print "\n"; + print "\n"; + print " ".$args{'function'}."\n"; + print " \n"; + print " ".$args{'purpose'}."\n"; + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." "; + print "\n"; + +# print "\n"; +# print " Synopsis\n"; +# print " \n"; +# print " ".$args{'functiontype'}." "; +# print "".$args{'function'}." "; +# print "\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1$parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + print "\n"; +# print "\n"; + + # print parameters + print "\n Arguments\n"; +# print "\nArguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " \n $parameter\n"; + print " \n \n"; + $lineprefix=" "; + output_highlight($args{'parameters'}{$parameter}); + print " \n \n \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print "\n"; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; +# print "\n$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); +# print ""; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } + + print "\n\n"; +} + +# output in sgml DocBook +sub output_intro_sgml { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; +# print "\n$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); +# print ""; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } + + print "\n\n"; +} + +# output in sgml DocBook +sub output_gnome { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}."-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print " ".$args{'function'}."\n"; + +# print "\n"; +# print " Synopsis\n"; + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." "; + print "\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; +# print "\n"; +# print "\n"; + + # print parameters +# print "\n Arguments\n"; +# if ($#{$args{'parameterlist'}} >= 0) { +# print " \n"; +# foreach $parameter (@{$args{'parameterlist'}}) { +# print " \n $parameter\n"; +# print " \n \n"; +# $lineprefix=" "; +# output_highlight($args{'parameters'}{$parameter}); +# print " \n \n \n"; +# } +# print " \n"; +# } else { +# print " \n None\n \n"; +# } +# print "\n"; + +# print "\n Arguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + print "\n"; + print "\n"; + print "\n"; + print "\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " $parameter\n"; + print " \n"; + $lineprefix=" "; + output_highlight($args{'parameters'}{$parameter}); + print " \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } +# print "\n"; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n"; +# print "\n$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print "\n"; + output_highlight($args{'sections'}{$section}); +# print ""; + print "\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print " \n"; + } + + print "\n\n"; +} + +## +# output in man +sub output_man { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 3 \"$args{'function'}\" \"25 May 1998\" \"API Manual\" libfaim\n"; + + print ".SH NAME\n"; + print $args{'function'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; + $count = 0; + $parenth = "("; + $post = ","; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($count == $#{$args{'parameterlist'}}) { + $post = ");"; + } + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n"; + } else { + $type =~ s/([^\*])$/\1 /; + print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n"; + } + $count++; + $parenth = ""; + } + + print ".SH Arguments\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameters'}{$parameter}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +sub output_intro_man { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 3 \"$args{'module'}\" \"25 May 1998\" \"API Manual\" libfaim\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output in text +sub output_text { + my %args = %{$_[0]}; + my ($parameter, $section); + + print "Function:\n\n"; + $start=$args{'functiontype'}." ".$args{'function'}." ("; + print $start; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print $1.$parameter.") (".$2; + } else { + print $type." ".$parameter; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + print " " x length($start); + } else { + print ");\n\n"; + } + } + + print "Arguments:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print $parameter."\n\t".$args{'parameters'}{$parameter}."\n"; + } + foreach $section (@{$args{'sectionlist'}}) { + print "$section:\n\n"; + output_highlight($args{'sections'}{$section}); + } + print "\n\n"; +} + +sub output_intro_text { + my %args = %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + print " $section:\n"; + print " -> "; + output_highlight($args{'sections'}{$section}); + } +} + +## +# generic output function - calls the right one based +# on current output mode. +sub output_function { +# output_html(@_); + eval "output_".$output_mode."(\@_);"; +} + +## +# generic output function - calls the right one based +# on current output mode. +sub output_intro { +# output_html(@_); + eval "output_intro_".$output_mode."(\@_);"; +} + + +## +# takes a function prototype and spits out all the details +# stored in the global arrays/hsahes. +sub dump_function { + my $prototype = shift @_; + + $prototype =~ s/^static+ //; + $prototype =~ s/^extern+ //; + $prototype =~ s/^inline+ //; + $prototype =~ s/^__inline__+ //; + $prototype =~ s/^faim_export+ //; + $prototype =~ s/^faim_internal+ //; + + if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $return_type = $1; + $function_name = $2; + $args = $3; + + # allow for up to fours args to function pointers + $args =~ s/(\([^\),]+),/\1#/g; + $args =~ s/(\([^\),]+),/\1#/g; + $args =~ s/(\([^\),]+),/\1#/g; +# print STDERR "ARGS = '$args'\n"; + + foreach $arg (split ',', $args) { + # strip leading/trailing spaces + $arg =~ s/^\s*//; + $arg =~ s/\s*$//; + + if ($arg =~ m/\(/) { + # pointer-to-function + $arg =~ tr/#/,/; + $arg =~ m/[^\(]+\(\*([^\)]+)\)/; + $param = $1; + $type = $arg; + $type =~ s/([^\(]+\(\*)$param/\1/; + } else { + # evil magic to get fixed array parameters to work + $arg =~ s/(.+\s+)(.+)\[.*/\1* \2/; +# print STDERR "SCAN ARG: '$arg'\n"; + @args = split('\s', $arg); + +# print STDERR " -> @args\n"; + $param = pop @args; +# print STDERR " -> @args\n"; + if ($param =~ m/^(\*+)(.*)/) { + $param = $2; + push @args, $1; + } + $type = join " ", @args; + } + + if ($type eq "" && $param eq "...") + { + $type="..."; + $param="..."; + $parameters{"..."} = "variable arguments"; + } + if ($type eq "") + { + $type=""; + $param="void"; + $parameters{void} = "no arguments"; + } + if ($parameters{$param} eq "") { + $parameters{$param} = "-- undescribed --"; + print STDERR "Warning($file:$lineno): Function parameter '$param' not described in '$function_name'\n"; + } + + push @parameterlist, $param; + $parametertypes{$param} = $type; +# print STDERR "param = '$param', type = '$type'\n"; + } + } else { + print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n"; + return; + } + + if ($function_only==0 || + ( $function_only == 1 && defined($function_table{$function_name})) || + ( $function_only == 2 && !defined($function_table{$function_name}))) + { + output_function({'function' => $function_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameters' => \%parameters, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $function_purpose + }); + } +} + +###################################################################### +# main +# states +# 0 - normal code +# 1 - looking for function name +# 2 - scanning field start. +# 3 - scanning prototype. +$state = 0; +$section = ""; + +$doc_special = "\@\%\$\&"; + +$doc_start = "^/\\*\\*\$"; +$doc_end = "\\*/"; +$doc_com = "\\s*\\*\\s*"; +$doc_func = $doc_com."(\\w+):?"; +$doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)"; +$doc_content = $doc_com."(.*)"; +$doc_block = $doc_com."DOC:\\s*(.*)?"; + +%constants = (); +%parameters = (); +@parameterlist = (); +%sections = (); +@sectionlist = (); + +$contents = ""; +$section_default = "Description"; # default section +$section_intro = "Introduction"; +$section = $section_default; + +$lineno = 0; +foreach $file (@ARGV) { + chomp($file); + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + next; + } + while () { + $lineno++; + + if ($state == 0) { + if (/$doc_start/o) { + $state = 1; # next line is always the function name + } + } elsif ($state == 1) { # this line is the function name (always) + if (/$doc_block/o) { + $state = 4; + $contents = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_func/o) { + $function = $1; + $state = 2; + if (/-(.*)/) { + $function_purpose = $1; + } else { + $function_purpose = ""; + } + if ($verbose) { + print STDERR "Info($lineno): Scanning doc for $function\n"; + } + } else { + print STDERR "WARN($lineno): Cannot understand $_ on line $lineno", + " - I thought it was a doc line\n"; + $state = 0; + } + } elsif ($state == 2) { # look for head: lines, and include content + if (/$doc_sect/o) { + $newsection = $1; + $newcontents = $2; + + if ($contents ne "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + } + + $contents = $newcontents; + if ($contents ne "") { + $contents .= "\n"; + } + $section = $newsection; + } elsif (/$doc_end/) { + + if ($contents ne "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } + +# print STDERR "end of doc comment, looking for prototype\n"; + $prototype = ""; + $state = 3; + } elsif (/$doc_content/) { + # miguel-style comment kludge, look for blank lines after + # @parameter line to signify start of description + if ($1 eq "" && $section =~ m/^@/) { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } else { + $contents .= $1."\n"; + } + } else { + # i dont know - bad line? ignore. + print STDERR "WARNING($lineno): bad line: $_"; + } + } elsif ($state == 3) { # scanning for function { (end of prototype) + if (m#\s*/\*\s+MACDOC\s*#io) { + # do nothing + } + elsif (/([^\{]*)/) { + $prototype .= $1; + } + if (/\{/) { + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =~ s@^ +@@gos; # strip leading spaces + dump_function($prototype); + + $function = ""; + %constants = (); + %parameters = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + + $state = 0; + } + } elsif ($state == 4) { + # Documentation block + if (/$doc_block/) { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameters = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_end/) + { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameters = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = 0; + } + elsif (/$doc_content/) + { + if ( $1 eq "" ) + { + $contents .= $blankline; + } + else + { + $contents .= $1 . "\n"; + } + } + } + } +} + diff --git a/utils/docs/split-man.pl b/utils/docs/split-man.pl new file mode 100755 index 0000000..86108f9 --- /dev/null +++ b/utils/docs/split-man.pl @@ -0,0 +1,23 @@ +#!/usr/bin/perl + +if ($#ARGV < 0) { + die "where do I put the results?\n"; +} + +mkdir $ARGV[0],0777 or die "Can't create $ARGV[0]: $!\n"; +$state = 0; +while () { + if (/^\.TH \"[^\"]*\" 3 \"([^\"]*)\"/) { + if ($state == 1) { close OUT } + $state = 1; + $fn = "$ARGV[0]/$1.3"; + print STDERR "Creating $fn\n"; + open OUT, ">$fn" or die "can't open $fn: $!\n"; + print OUT $_; + } elsif ($state != 0) { + print OUT $_; + } +} + +close OUT; + -- 2.45.1