From 4c5f93d76bd0636407a185c175fe73411ae79a32 Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Mon, 5 Jun 2000 17:13:36 +0000 Subject: [PATCH] Better documentation. There are functions whose description is good when reading source but whose documentation does not belong to progdocs. --- filter/filter.c | 19 ++++++++++------- proto/rip/auth.c | 4 ++-- proto/rip/rip.c | 54 +++++++++++++++++++++++++++++++----------------- 3 files changed, 48 insertions(+), 29 deletions(-) diff --git a/filter/filter.c b/filter/filter.c index 1e6fa905..1069f642 100644 --- a/filter/filter.c +++ b/filter/filter.c @@ -30,7 +30,8 @@ * forced. Important thing about &f_val s is that they may be copied * with simple =. That's fine for all currently defined types: strings * are read-only (and therefore okay), paths are copied for each - * operation (okay too). */ + * operation (okay too). + */ #undef LOCAL_DEBUG @@ -70,7 +71,7 @@ pm_path_compare(struct f_path_mask *m1, struct f_path_mask *m2) } } -/** +/* * val_compare - compare two values, returns -1, 0, 1 on <, =, > and 999 on error */ int @@ -105,7 +106,7 @@ val_compare(struct f_val v1, struct f_val v2) } } -/** +/* * val_simple_in_range - check if @v1 ~ @v2 for everything except sets */ int @@ -139,7 +140,7 @@ val_simple_in_range(struct f_val v1, struct f_val v2) return CMP_ERROR; } -/** +/* * val_in_range - check if @v1 ~ @v2 */ int @@ -183,7 +184,7 @@ tree_print(struct f_tree *t) debug( "] " ); } -/** +/* * val_print - format filter value */ void @@ -218,7 +219,7 @@ static struct ea_list **f_tmp_attrs; static int f_flags; static rta *f_rta_copy; -/** +/* * rta_cow - prepare rta for modification by filter */ void @@ -257,7 +258,7 @@ rta_cow(void) * interpret * @what: filter to interrpret * - * Interrpret given tree of filter instructions. This is core function + * Interpret given tree of filter instructions. This is core function * of filter system and does all the hard work. */ static struct f_val @@ -681,7 +682,7 @@ interpret(struct f_inst *what) #define A2_SAME if (f1->a2.i != f2->a2.i) return 0; -/** +/* * i_same - function that does real comparing of instruction trees, you should call filter_same from outside */ int @@ -765,8 +766,10 @@ i_same(struct f_inst *f1, struct f_inst *f2) /** * f_run - external entry point to filters * @filter: pointer to filter to run + * @tmp_attrs: where to store newly generated temporary attributes * @rte: pointer to pointer to rte being filtered. When route is modified, this is changed with rte_cow. * @tmp_pool: all filter allocations go from this pool + * @flags: flags */ int f_run(struct filter *filter, struct rte **rte, struct ea_list **tmp_attrs, struct linpool *tmp_pool, int flags) diff --git a/proto/rip/auth.c b/proto/rip/auth.c index f1a3204e..c23872be 100644 --- a/proto/rip/auth.c +++ b/proto/rip/auth.c @@ -26,7 +26,7 @@ #define PACKETLEN(num) (num * sizeof(struct rip_block) + sizeof(struct rip_packet_heading)) -/** +/* * rip_incoming_authentication - check authentication of incomming packet and return 1 if there's problem. */ int @@ -110,7 +110,7 @@ rip_incoming_authentication( struct proto *p, struct rip_block_auth *block, stru return 0; } -/** +/* * rip_outgoing_authentication - append authentication information to the packet. * %num: number of rip_blocks already in packets. This function returns size of packet to send. */ diff --git a/proto/rip/rip.c b/proto/rip/rip.c index 643fc432..7cefe89b 100644 --- a/proto/rip/rip.c +++ b/proto/rip/rip.c @@ -22,7 +22,11 @@ * * Rip is pretty simple protocol so half of this code is interface * with core. We maintain our own linklist of &rip_entry - it serves - * as our small routing table. Within rip_tx(), this list is + * as our small routing table. Rip never adds into this linklist at + * packet reception; instead, it lets core know about data from packet, + * and waits for core to call our rip_rte_notify. + * + * Within rip_tx(), this list is * walked, and packet is generated using rip_tx_prepare(). This gets * tricky because we may need to send more than one packet to one * destination. Struct &rip_connection is used to hold info such as how @@ -65,7 +69,7 @@ static struct rip_interface *new_iface(struct proto *p, struct iface *new, unsig #define P_NAME p->name -/** +/* * DOC: Output processing * * This part is responsible for getting packets out to the network. @@ -79,7 +83,7 @@ rip_tx_err( sock *s, int err ) log( L_ERR "%s: Unexpected error at rip transmit: %M", P_NAME, err ); } -/** +/* * rip_tx_prepare: * @e: rip entry that needs to be translated to form suitable for network * @b: block to be filled @@ -117,7 +121,7 @@ rip_tx_prepare(struct proto *p, ip_addr daddr, struct rip_block *b, struct rip_e return pos+1; } -/** +/* * rip_tx - send one rip packet to the network */ static void @@ -195,7 +199,7 @@ done: return; } -/** +/* * rip_sendto - send whole routing table to selected destination * @rif: interface to use. Notice that we lock interface so that at * most one send to one interface is done. @@ -246,7 +250,7 @@ find_interface(struct proto *p, struct iface *what) return NULL; } -/** +/* * DOC: Input processing * * This part is responsible for any updates that come from network @@ -262,13 +266,12 @@ rip_rte_update_if_better(rtable *tab, net *net, struct proto *p, rte *new) rte_update(tab, net, p, new); } -/** +/* * advertise_entry - let main routing table know about our new entry * @b: entry in network format * * This basically translates @b to format used by bird core and feeds - * bird core with this route. Notice that we do not store info anywhere - * in our data structures: we'll do that when core notifies us back. + * bird core with this route. */ static void advertise_entry( struct proto *p, struct rip_block *b, ip_addr whotoldme ) @@ -334,7 +337,7 @@ advertise_entry( struct proto *p, struct rip_block *b, ip_addr whotoldme ) DBG( "done\n" ); } -/** +/* * process_block - do some basic check and pass block to advertise_entry */ static void @@ -360,7 +363,7 @@ process_block( struct proto *p, struct rip_block *block, ip_addr whotoldme ) #define BAD( x ) { log( L_REMOTE "%s: " x, P_NAME ); return 1; } -/** +/* * rip_process_packet - this is main routine for incoming packets. */ static int @@ -430,7 +433,7 @@ rip_process_packet( struct proto *p, struct rip_packet *packet, int num, ip_addr return 0; } -/** +/* * rip_rx - Receive hook: do basic checks and pass packet to rip_process_packet */ static int @@ -462,7 +465,7 @@ rip_rx(sock *s, int size) return 1; } -/** +/* * DOC: Interface to bird core */ @@ -475,8 +478,16 @@ rip_dump_entry( struct rip_entry *e ) } /** - * rip_timer - broadcast routing tables periodically (using rip_tx) and kill routes that are too old + * rip_timer + * @t: timer + * + * Broadcast routing tables periodically (using rip_tx) and kill + * routes that are too old. Rip keeps its own entries in main routing + * table linked by link list (functions rip_rte_insert and + * rip_rte_delete are responsible for that), walks this list in timer + * and in case entry is too old, it is discarded. */ + static void rip_timer(timer *t) { @@ -530,7 +541,7 @@ rip_timer(timer *t) DBG( "RIP: tick tock done\n" ); } -/** +/* * rip_start - initialize instance of rip */ static int @@ -623,10 +634,15 @@ kill_iface(struct proto *p, struct rip_interface *i) } /** - * new_iface - actually create struct interface and start listening to it + * new_iface + * @p: myself * @new: interface to be created or %NULL if we are creating magic * socket. Magic socket is used for listening, and is also used for * sending requested responses. + * @flags: interface flags + * @patt: pattern this interface matched, used for access to config options + * + * actually create struct interface and start listening to it */ static struct rip_interface * new_iface(struct proto *p, struct iface *new, unsigned long flags, struct iface_patt *patt ) @@ -810,7 +826,7 @@ rip_store_tmp_attrs(struct rte *rt, struct ea_list *attrs) rt->u.rip.metric = ea_get_int(attrs, EA_RIP_METRIC, 1); } -/** +/* * rip_rt_notify - core tells us about new route (possibly our * own), so store it into our data structures. */ @@ -882,7 +898,7 @@ rip_rte_better(struct rte *new, struct rte *old) return 0; } -/** +/* * rip_rte_insert - we maintain linked list of "our" entries in main * routing table, so that we can timeout them correctly. rip_timer * walks the list. @@ -897,7 +913,7 @@ rip_rte_insert(net *net, rte *rte) add_head( &P->garbage, &rte->u.rip.garbage ); } -/** +/* * rip_rte_remove - link list maintenance */ static void