--------------------- PatchSet 5047 Date: 2007/07/11 23:35:00 Author: amosjeffries Branch: docs Tag: (none) Log: Update old guide content comments to not screw up the auto-build. Members: doc/Programming-Guide/01_Main.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/02_CodingConventions.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/03_MajorComponents.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/04_ExternalPrograms.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/07_MainLoop.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/08_ClientStreams.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/09_ClientRequests.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/12_StorageInterface.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/16_Timeouts.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/19_AuthenticationFramework.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/23_CallbackDataAllocator.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/24_RefCountDataAllocator.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/26_HTTPHeaders.dox:1.1.2.1->1.1.2.2 doc/Programming-Guide/27_MiscOther.dox:1.1.2.1->1.1.2.2 Index: squid3/doc/Programming-Guide/01_Main.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/01_Main.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/01_Main.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/01_Main.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,4 +1,5 @@ -/** \mainpage Squid 3.x Developer Programming Guide +/** +\mainpage Squid 3.x Developer Programming Guide \section Abstract Abstract @@ -49,7 +50,7 @@ do make some effort to document code as we go some parts of the documentation may be left out. If you find any inconsistencies, please feel free to notify - \link http://www.squid-cache.org/Support/contact.dyn the Squid Developers \endlink + \link /Support/contact.dyn the Squid Developers \endlink . */ Index: squid3/doc/Programming-Guide/02_CodingConventions.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/02_CodingConventions.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/02_CodingConventions.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/02_CodingConventions.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,5 +1,5 @@ /** -\page 01_CodeConventions Coding Conventions +\page 02_CodeConventions Coding Conventions \section Infrastructure Infrastructure Index: squid3/doc/Programming-Guide/03_MajorComponents.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/03_MajorComponents.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/03_MajorComponents.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/03_MajorComponents.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,5 +1,5 @@ /** -\page 02_MajorComponents Overview of Squid Components +\page 03_MajorComponents Overview of Squid Components \par Squid consists of the following major components Index: squid3/doc/Programming-Guide/04_ExternalPrograms.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/04_ExternalPrograms.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/04_ExternalPrograms.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/04_ExternalPrograms.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,5 +1,5 @@ /** -\page 03_ExternalPrograms External Programs +\page 04_ExternalPrograms External Programs \section dnsserver dnsserver \par @@ -8,7 +8,7 @@ these calls. Typically there will be ten dnsserver processes spawned from Squid. Communication occurs via TCP sockets bound to the loopback interface. The functions - in dns.c are primarily concerned with starting and + in dns.cc are primarily concerned with starting and stopping the dnsservers. Reading and writing to and from the dnsservers occurs in the IP and FQDN cache modules. Index: squid3/doc/Programming-Guide/07_MainLoop.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/07_MainLoop.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/07_MainLoop.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/07_MainLoop.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,5 +1,5 @@ /** -\page 7_MainLoop The Main Loop: comm_select() +\page 07_MainLoop The Main Loop: comm_select() \par At the core of Squid is the select(2) system call. Squid uses select() or poll(2) to process I/O on Index: squid3/doc/Programming-Guide/08_ClientStreams.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/08_ClientStreams.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/08_ClientStreams.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/08_ClientStreams.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,5 +1,5 @@ /** -\page 8_ClientStreams Client Streams +\page 08_ClientStreams Client Streams \todo DOCS: this seems all to be a better fit as inline code comments. @@ -13,8 +13,8 @@ \par clientStream is the basic unit for scheduling, and the clientStreamRead and clientStreamCallback calls allow for deferred scheduled activity if desired. -\par - Theory on stream operation: + +\par Theory on stream operation: \li Something creates a pipeline. At a minimum it needs a head with a status method and a read method, and a tail with a callback method and a valid initial read request. @@ -51,7 +51,9 @@ previous code to send the data. This is a TODO when time permits. \section WhatsInANode Whats in a node + \todo ClientStreams: These details should really be codified as a class which all ClientStream nodes inherit from. + \par Each node must have: \li read method - to allow loose coupling in the pipeline. (The reader may therefore change if the pipeline is altered, even mid-flow). Index: squid3/doc/Programming-Guide/09_ClientRequests.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/09_ClientRequests.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/09_ClientRequests.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/09_ClientRequests.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,5 +1,5 @@ /** -\page 9_ClientRequests Processing Client Requests +\page 09_ClientRequests Processing Client Requests \todo DOCS: write this section. Or at least find place in the code autodocs to write it. Index: squid3/doc/Programming-Guide/12_StorageInterface.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/12_StorageInterface.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/12_StorageInterface.dox 11 Jul 2007 05:32:06 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/12_StorageInterface.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -44,13 +44,9 @@ to generate the initialisation function storeFsSetup(). This function lives in store_modules.c. -\par - An example of the automatically generated file: - +\par Example of the automatically generated file: + automatically generated by ./store_modules.sh ufs coss do not edit \code - /* automatically generated by ./store_modules.sh ufs coss - * do not edit - */ #include "squid.h" extern STSETUP storeFsSetup_ufs; @@ -117,7 +113,7 @@ line can be retrieved through calls to strtok() and GetInteger(). \par STFSPARSE - has the task of initialising a new swapdir. It should + has the task of initialising a new swapdir. It should parse the remaining arguments on the cache_dir line, initialise the relevant function pointers and data structures, and choose the replacement policy. STFSRECONFIGURE deals with reconfiguring an @@ -129,15 +125,15 @@ \par \code struct _SwapDir { - char *type; /* Pointer to the store dir type string */ - int cur_size; /* Current swapsize in kb */ - int low_size; /* ?? */ - int max_size; /* Maximum swapsize in kb */ - char *path; /* Path to store */ - int index; /* This entry's index into the swapDir array */ - int suggest; /* Suggestion for UFS style stores (??) */ - size_t max_objsize; /* Maximum object size for this store */ - union { /* Replacement policy-specific fields */ + char *type; // Pointer to the store dir type string + int cur_size; // Current swapsize in kb + int low_size; // ?? + int max_size; // Maximum swapsize in kb + char *path; // Path to store + int index; // This entry's index into the swapDir array + int suggest; // Suggestion for UFS style stores (??) + size_t max_objsize; // Maximum object size for this store + union { // Replacement policy-specific fields #ifdef HEAP_REPLACEMENT struct { heap *heap; @@ -151,41 +147,41 @@ int removals; int scanned; struct { - unsigned int selected:1; /* Currently selected for write */ - unsigned int read_only:1; /* This store is read only */ + unsigned int selected:1; // Currently selected for write + unsigned int read_only:1; // This store is read only } flags; - STINIT *init; /* Initialise the fs */ - STNEWFS *newfs; /* Create a new fs */ - STDUMP *dump; /* Dump fs config snippet */ - STFREE *freefs; /* Free the fs data */ - STDBLCHECK *dblcheck; /* Double check the obj integrity */ - STSTATFS *statfs; /* Dump fs statistics */ - STMAINTAINFS *maintainfs; /* Replacement maintainence */ - STCHECKOBJ *checkob; /* Check if the fs will store an object, and get the FS load */ - /* These two are notifications */ - STREFOBJ *refobj; /* Reference this object */ - STUNREFOBJ *unrefobj; /* Unreference this object */ - STCALLBACK *callback; /* Handle pending callbacks */ - STSYNC *sync; /* Sync the directory */ + STINIT *init; // Initialise the fs + STNEWFS *newfs; // Create a new fs + STDUMP *dump; // Dump fs config snippet + STFREE *freefs; // Free the fs data + STDBLCHECK *dblcheck; // Double check the obj integrity + STSTATFS *statfs; // Dump fs statistics + STMAINTAINFS *maintainfs; // Replacement maintainence + STCHECKOBJ *checkob; // Check if the fs will store an object, and get the FS load + // These two are notifications + STREFOBJ *refobj; // Reference this object + STUNREFOBJ *unrefobj; // Unreference this object + STCALLBACK *callback; // Handle pending callbacks + STSYNC *sync; // Sync the directory struct { - STOBJCREATE *create; /* Create a new object */ - STOBJOPEN *open; /* Open an existing object */ - STOBJCLOSE *close; /* Close an open object */ - STOBJREAD *read; /* Read from an open object */ - STOBJWRITE *write; /* Write to a created object */ - STOBJUNLINK *unlink; /* Remove the given object */ + STOBJCREATE *create; // Create a new object + STOBJOPEN *open; // Open an existing object + STOBJCLOSE *close; // Close an open object + STOBJREAD *read; // Read from an open object + STOBJWRITE *write; // Write to a created object + STOBJUNLINK *unlink; // Remove the given object } obj; struct { - STLOGOPEN *open; /* Open the log */ - STLOGCLOSE *close; /* Close the log */ - STLOGWRITE *write; /* Write to the log */ + STLOGOPEN *open; // Open the log + STLOGCLOSE *close; // Close the log + STLOGWRITE *write; // Write to the log struct { - STLOGCLEANOPEN *open; /* Open a clean log */ - STLOGCLEANWRITE *write; /* Write to the log */ - void *state; /* Current state */ + STLOGCLEANOPEN *open; // Open a clean log + STLOGCLEANWRITE *write; // Write to the log + void *state; // Current state } clean; } log; - void *fsdata; /* FS-specific data */ + void *fsdata; // FS-specific data }; \endcode @@ -204,23 +200,23 @@ \par \code struct _storeIOState { - sdirno swap_dirn; /* SwapDir index */ - sfileno swap_filen; /* Unique file index number */ - StoreEntry *e; /* Pointer to parent StoreEntry */ - mode_t mode; /* Mode - O_RDONLY or O_WRONLY */ - size_t st_size; /* Size of the object if known */ - off_t offset; /* current _on-disk_ offset pointer */ - STFNCB *file_callback; /* called on delayed sfileno assignments */ - STIOCB *callback; /* IO Error handler callback */ - void *callback_data; /* IO Error handler callback data */ + sdirno swap_dirn; // SwapDir index + sfileno swap_filen; // Unique file index number + StoreEntry *e; // Pointer to parent StoreEntry + mode_t mode; // Mode - O_RDONLY or O_WRONLY + size_t st_size; // Size of the object if known + off_t offset; // current _on-disk_ offset pointer + STFNCB *file_callback; // called on delayed sfileno assignments + STIOCB *callback; // IO Error handler callback + void *callback_data; // IO Error handler callback data struct { - STRCB *callback; /* Read completion callback */ - void *callback_data; /* Read complation callback data */ + STRCB *callback; // Read completion callback + void *callback_data; // Read complation callback data } read; struct { - unsigned int closing:1; /* debugging aid */ + unsigned int closing:1; // debugging aid } flags; - void *fsstate; /* pointer to private fs state */ + void *fsstate; // pointer to private fs state }; \endcode @@ -988,7 +984,7 @@ char *_type; void *_data; void (*add)(RemovalPolicy *policy, StoreEntry *); - ... /* see the API definition above */ + ... // see the API definition above }; \endcode @@ -1008,7 +1004,7 @@ RemovalPolicy *_policy; void *_data; StoreEntry *(*next)(RemovalPolicyWalker *); - ... /* see the API definition above */ + ... // see the API definition above }; \endcode Index: squid3/doc/Programming-Guide/16_Timeouts.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/16_Timeouts.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/16_Timeouts.dox 11 Jul 2007 05:32:07 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/16_Timeouts.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,5 +1,5 @@ /** -\page 16 Timeouts Timeouts +\page 16_Timeouts Timeouts \section Infrastructure Infrastructure Index: squid3/doc/Programming-Guide/19_AuthenticationFramework.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/19_AuthenticationFramework.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/19_AuthenticationFramework.dox 11 Jul 2007 05:32:10 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/19_AuthenticationFramework.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -1,4 +1,4 @@ -/* +/** \page 19_AuthenticationFramework Authentication Framework \par @@ -248,11 +248,11 @@ \code struct _auth_user_hash_pointer { - /* first two items must be same as hash_link */ + // first two items must be same as hash_link char *key; auth_user_hash_pointer *next; auth_user_t *auth_user; - dlink_node link; /* other hash entries that point to the same auth_user */ + dlink_node link; // other hash entries that point to the same auth_user }; \endcode @@ -265,29 +265,29 @@ \code struct _auth_user_t { - /* extra fields for proxy_auth */ - /* this determines what scheme owns the user data. */ + // extra fields for proxy_auth + // this determines what scheme owns the user data. auth_type_t auth_type; - /* the index +1 in the authscheme_list to the authscheme entry */ + // the index +1 in the authscheme_list to the authscheme entry int auth_module; - /* we only have one username associated with a given auth_user struct */ + // we only have one username associated with a given auth_user struct auth_user_hash_pointer *usernamehash; - /* we may have many proxy-authenticate strings that decode to the same user*/ + // we may have many proxy-authenticate strings that decode to the same user dlink_list proxy_auth_list; dlink_list proxy_match_cache; struct { - unsigned int credentials_ok:2; /*0=unchecked,1=ok,2=failed*/ + unsigned int credentials_ok:2; // 0=unchecked,1=ok,2=failed } flags; long expiretime; - /* IP addr this user authenticated from */ + // IP addr this user authenticated from struct IN_ADDR ipaddr; time_t ip_expiretime; - /* how many references are outstanding to this instance*/ + // how many references are outstanding to this instance size_t references; - /* the auth scheme has it's own private data area */ + // the auth scheme has it's own private data area void *scheme_data; - /* the auth_user_request structures that link to this. Yes it could be a splaytree - * but how many requests will a single username have in parallel? */ + // the auth_user_request structures that link to this. Yes it could be a splaytree + // but how many requests will a single username have in parallel? dlink_list requests; }; \endcode @@ -298,15 +298,14 @@ \code struct _auth_user_request_t { - /* this is the object passed around by client_side and acl functions */ - /* it has request specific data, and links to user specific data */ - /* the user */ + // this is the object passed around by client_side and acl functions + // it has request specific data, and links to user specific data the user auth_user_t *auth_user; - /* return a message on the 401/407 error pages */ + // return a message on the 401/407 error pages char *message; - /* any scheme specific request related data */ + // any scheme specific request related data void *scheme_data; - /* how many 'processes' are working on this data */ + // how many 'processes' are working on this data size_t references; }; \endcode @@ -332,7 +331,7 @@ AUTHSFREE *FreeUser; AUTHSFREECONFIG *freeconfig; AUTHSUSERNAME *authUserUsername; - AUTHSONCLOSEC *oncloseconnection; /*optional*/ + AUTHSONCLOSEC *oncloseconnection; // optional AUTHSDECODE *decodeauth; AUTHSDIRECTION *getdirection; AUTHSPARSE *parse; Index: squid3/doc/Programming-Guide/23_CallbackDataAllocator.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/23_CallbackDataAllocator.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/23_CallbackDataAllocator.dox 11 Jul 2007 05:32:10 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/23_CallbackDataAllocator.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -31,10 +31,10 @@ \subsection CBDATA_GLOBAL_TYPE CBDATA_GLOBAL_TYPE \code - /* Module header file */ + // Module header file external CBDATA_GLOBAL_TYPE(datatype); - /* Module main C file */ + // Module main C file CBDATA_GLOBAL_TYPE(datatype); \endcode @@ -45,7 +45,7 @@ \subsectino CBDATA_INIT_TYPE CBDATA_INIT_TYPE \code CBDATA_INIT_TYPE(datatype); - /* or */ + // or CBDATA_INIT_TYPE_FREECB(datatype, FREE *freehandler); \endcode @@ -147,17 +147,17 @@ sequence of events in programs NOT using cbdata is as follows: \code - /* initialization */ + // initialization type_of_data our_data; ... our_data = malloc(...); ... - /* Initiate a asyncronous operation, with our_data as callback_data */ + // Initiate a asyncronous operation, with our_data as callback_data fooOperationStart(bar, callback_func, our_data); ... - /* The asyncronous operation completes and makes the callback */ + // The asyncronous operation completes and makes the callback callback_func(callback_data, ....); - /* Some time later we clean up our data */ + // Some time later we clean up our data free(our_data); \endcode @@ -170,27 +170,25 @@ causing a program failure or memory corruption: \code - /* initialization */ + // initialization type_of_data our_data; ... our_data = malloc(...); ... - /* Initiate a asyncronous operation, with our_data as callback_data */ + // Initiate a asyncronous operation, with our_data as callback_data fooOperationStart(bar, callback_func, our_data); ... - /* ouch, something bad happened elsewhere.. try to cleanup - * but the programmer forgot there is a callback pending from - * fooOperationsStart() (an easy thing to forget when writing code - * to deal with errors, especially if there may be many different - * pending operation) - */ + // ouch, something bad happened elsewhere.. try to cleanup + // but the programmer forgot there is a callback pending from + // fooOperationsStart() (an easy thing to forget when writing code + // to deal with errors, especially if there may be many different + // pending operation) free(our_data); ... - /* The asyncronous operation completes and makes the callback */ + // The asyncronous operation completes and makes the callback callback_func(callback_data, ....); - /* CRASH, the memory pointer to by callback_data is no longer valid - * at the time of the callback - */ + // CRASH, the memory pointer to by callback_data is no longer valid + // at the time of the callback \endcode \subsection AsyncOpWithCBDATA Asyncronous operation with cbdata @@ -204,18 +202,18 @@ completes. The normal sequence of events is: \code - /* initialization */ + // initialization type_of_data our_data; ... our_data = cbdataAlloc(type_of_data); ... - /* Initiate a asyncronous operation, with our_data as callback_data */ + // Initiate a asyncronous operation, with our_data as callback_data fooOperationStart(..., callback_func, our_data); ... - /* foo */ + // foo void *local_pointer = cbdataReference(callback_data); .... - /* The asyncronous operation completes and makes the callback */ + // The asyncronous operation completes and makes the callback void *cbdata; if (cbdataReferenceValidDone(local_pointer, &cbdata)) callback_func(...., cbdata); @@ -229,27 +227,35 @@ With this scheme, nothing bad happens if cbdataFree gets called before fooOperantionComplete(...). +\par + Initalization \code - /* initialization */ type_of_data our_data; ... our_data = cbdataAlloc(type_of_data); - ... - /* Initiate a asyncronous operation, with our_data as callback_data */ +\endcode + Initiate a asyncronous operation, with our_data as callback_data +\code fooOperationStart(..., callback_func, our_data); - ... - /* foo */ +\endcode + do some stuff with it +\code void *local_pointer = cbdataReference(callback_data); - .... - /* something bad happened elsewhere.. cleanup */ +\endcode + something bad happened elsewhere.. cleanup +\code cbdataFree(our_data); - ... - /* The asyncronous operation completes and tries to make the callback */ +\endcode + The asyncronous operation completes and tries to make the callback +\code void *cbdata; if (cbdataReferenceValidDone(local_pointer, &cbdata)) - /* won't be called, as the data is no longer valid */ + { +\endcode + won't be called, as the data is no longer valid +\code callback_func(...., cbdata); - + } \endcode \par @@ -266,23 +272,25 @@ macros CBDATA_TYPE and CBDATA_INIT_TYPE. These creates a local cbdata definition (file or block scope). Any cbdataAlloc calls must be made within this scope. However, cbdataFree might be called from anywhere. + +\par + First the cbdata type needs to be defined in the module. This + is usually done at file scope, but it can also be local to a + function or block.. \code - /* First the cbdata type needs to be defined in the module. This - * is usually done at file scope, but it can also be local to a - * function or block.. - */ CBDATA_TYPE(type_of_data); - - /* Then in the code somewhere before the first allocation - * (can be called multiple times with only a minimal overhead) - */ +\endcode + Then in the code somewhere before the first allocation + (can be called multiple times with only a minimal overhead) +\code CBDATA_INIT_TYPE(type_of_data); - /* Or if a free function is associated with the data type. This - * function is responsible for cleaning up any dependencies etc - * referenced by the structure and is called on cbdataFree or - * when the last reference is deleted by cbdataReferenceDone / - * cbdataReferenceValidDone - */ +\endcode + Or if a free function is associated with the data type. This + function is responsible for cleaning up any dependencies etc + referenced by the structure and is called on cbdataFree or + when the last reference is deleted by cbdataReferenceDone / + cbdataReferenceValidDone +\code CBDATA_INIT_TYPE_FREECB(type_of_data, free_function); \endcode @@ -297,7 +305,7 @@ the appropriate location(s) as described above. \code - extern CBDATA_GLOBAL_TYPE(type_of_data); /* CBDATA_UNDEF */ + extern CBDATA_GLOBAL_TYPE(type_of_data); // CBDATA_UNDEF \endcode */ Index: squid3/doc/Programming-Guide/24_RefCountDataAllocator.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/24_RefCountDataAllocator.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/24_RefCountDataAllocator.dox 11 Jul 2007 05:32:10 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/24_RefCountDataAllocator.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -62,7 +62,7 @@ }; ... - /* In your .cc file */ + // In your .cc file CBDATA_CLASS_INIT(MyConcrete); void * @@ -70,9 +70,7 @@ { CBDATA_INIT_TYPE(MyConcrete); MyConcrete *result = cbdataAlloc(MyConcrete); - /* Mark result as being owned - we want the refcounter to do the - * delete call - */ + // Mark result as being owned - we want the refcounter to do the delete call cbdataReference(result); return result; } @@ -82,7 +80,7 @@ { MyConcrete *t = static_cast(address); cbdataFree(address); - /* And allow the memory to be freed */ + // And allow the memory to be freed cbdataReferenceDone (t); } \endcode @@ -127,13 +125,12 @@ \code void MyConcrete::aMethod(){ - /* This holds a reference to us */ + // This holds a reference to us Pointer aPointer(this); - /* This is a method that may mean we don't need to exist anymore */ + // This is a method that may mean we don't need to exist anymore someObject->someMethod(); - /* This prevents aPointer being optimised away before this point, - * and must be the last line in our method - */ + // This prevents aPointer being optimised away before this point, + // and must be the last line in our method aPointer = NULL; } \endcode Index: squid3/doc/Programming-Guide/26_HTTPHeaders.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/26_HTTPHeaders.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/26_HTTPHeaders.dox 11 Jul 2007 05:32:10 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/26_HTTPHeaders.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -38,16 +38,16 @@ cleaning: \code - /* declare */ + // declare HttpHeader hdr; - /* initialize (as an HTTP Request header) */ + // initialize (as an HTTP Request header) httpHeaderInit(&hdr, hoRequest); - /* do something */ + // do something ... - /* cleanup */ + // cleanup httpHeaderClean(&hdr); \endcode @@ -118,9 +118,8 @@ methods is converted to and stored as a String object. \par Example: - + Add our own Age: field if none was added before \code - /* add our own Age field if none was added before */ int age = ... if (!httpHeaderHas(hdr, HDR_AGE)) httpHeaderPutInt(hdr, HDR_AGE, age); @@ -142,13 +141,14 @@ is also safe to delete/add fields from/to hdr while iteration is in progress. +\par Example: + Delete al fields with a given name \code - /* delete all fields with a given name */ HttpHeaderPos pos = HttpHeaderInitPos; HttpHeaderEntry *e; while ((e = httpHeaderGetEntry(hdr, &pos))) { if (!strCaseCmp(e->name, name)) - ... /* delete entry */ + ... // delete entry } \endcode Index: squid3/doc/Programming-Guide/27_MiscOther.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/27_MiscOther.dox,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- squid3/doc/Programming-Guide/27_MiscOther.dox 11 Jul 2007 05:32:10 -0000 1.1.2.1 +++ squid3/doc/Programming-Guide/27_MiscOther.dox 11 Jul 2007 23:35:00 -0000 1.1.2.2 @@ -404,20 +404,20 @@ int overhead; }; - /* object to track per-pool cumulative counters */ + // object to track per-pool cumulative counters typedef struct { double count; double bytes; } mgb_t; - /* object to track per-pool memory usage (alloc = inuse+idle) */ + // object to track per-pool memory usage (alloc = inuse+idle) struct _MemPoolMeter { MemMeter alloc; MemMeter inuse; MemMeter idle; - mgb_t gb_saved; /* account Allocations */ - mgb_t gb_osaved; /* history Allocations */ - mgb_t gb_freed; /* account Free calls */ + mgb_t gb_saved; // account Allocations + mgb_t gb_osaved; // history Allocations + mgb_t gb_freed; // account Free calls }; \endcode