--------------------- PatchSet 5334 Date: 2007/08/15 02:32:56 Author: amosjeffries Branch: docs Tag: (none) Log: Commenting style change. Members: doc/Programming-Guide/Groups.dox:1.1.2.10->1.1.2.11 include/MemPool.h:1.10.10.1->1.10.10.2 src/ACL.h:1.18.10.3->1.18.10.4 src/AuthConfig.h:1.3.2.2->1.3.2.3 src/AuthUserRequest.h:1.8.2.5->1.8.2.6 src/URL.h:1.1.24.1->1.1.24.2 src/authenticate.h:1.14.14.1->1.14.14.2 src/cbdata.h:1.1.22.3->1.1.22.4 src/clientStream.cc:1.11.2.4->1.11.2.5 src/fqdncache.cc:1.19.2.2->1.19.2.3 src/ipcache.cc:1.20.2.2->1.20.2.3 src/fs/aufs/StoreFSaufs.cc:1.2.24.2->1.2.24.3 src/fs/coss/StoreFScoss.h:1.3.14.1->1.3.14.2 src/fs/coss/store_coss.h:1.14.10.3->1.14.10.4 src/fs/diskd/StoreFSdiskd.cc:1.2.24.2->1.2.24.3 src/fs/null/StoreFSnull.h:1.1.32.1->1.1.32.2 src/fs/ufs/StoreFSufs.h:1.5.10.2->1.5.10.3 src/fs/ufs/ufscommon.h:1.9.10.4->1.9.10.5 Index: squid3/doc/Programming-Guide/Groups.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/Groups.dox,v retrieving revision 1.1.2.10 retrieving revision 1.1.2.11 diff -u -r1.1.2.10 -r1.1.2.11 --- squid3/doc/Programming-Guide/Groups.dox 10 Aug 2007 00:12:56 -0000 1.1.2.10 +++ squid3/doc/Programming-Guide/Groups.dox 15 Aug 2007 02:32:56 -0000 1.1.2.11 @@ -1,7 +1,7 @@ /** - * \defgroup POD POD Classes + \defgroup POD POD Classes * - * \par + \par * Classes which encapsulate POD (plain old data) in such a way * that they can be used as POD themselves and passed around Squid. * These objects should have a formal API for safe handling of their @@ -10,41 +10,40 @@ */ /** - * \defgroup Components Squid Components - * + \defgroup Components Squid Components */ /** \defgroup ServerProtocol Server-Side Protocols \ingroup Components \par - These routines are responsible for forwarding cache misses - to other servers, depending on the protocol. Cache misses - may be forwarded to either origin servers, or other proxy - caches. - All requests to other proxies are sent as HTTP requests. - All requests to origin-server are sent in that servers protocol. - + * These routines are responsible for forwarding cache misses + * to other servers, depending on the protocol. Cache misses + * may be forwarded to either origin servers, or other proxy + * caches. + * All requests to other proxies are sent as HTTP requests. + * All requests to origin-server are sent in that servers protocol. + * \par - Wais and Gopher don't receive much - attention because they comprise a relatively insignificant - portion of Internet traffic. + * Wais and Gopher don't receive much + * attention because they comprise a relatively insignificant + * portion of Internet traffic. */ /** - * \defgroup libsquid Squid Library + \defgroup libsquid Squid Library * - * \par + \par * These objects are provided publicly through lidsquid.la */ /** - * \defgroup Tests Unit Testing + \defgroup Tests Unit Testing * - * \par + \par * Any good application has a set of tests to ensure it stays * in a good condition. Squid tends to use cppunit tests. - * \par + \par * It is preferrable to automated tests for units of functionality. There * is a boilerplate for tests in "src/tests/testBoilerplate.[cc|h]". New * tests need to be added to src/Makefile.am to build and run them during @@ -57,39 +56,39 @@ */ /** - * \defgroup Callbacks Event Callback Functions + \defgroup Callbacks Event Callback Functions * - * \par + \par * Squid uses events to process asynchronous actions. * These mehods are registered as callbacks to receive notice whenever a * specific event occurs. */ /** - * \defgroup Timeouts Timeouts - * \todo DOCS: document Timeouts. + \defgroup Timeouts Timeouts + \todo DOCS: document Timeouts. */ /** - * \defgroup ServerProtocolHTTP HTTP - * \ingroup ServerProtocol - * \todo Write Documentation about HTTP + \defgroup ServerProtocolHTTP HTTP + \ingroup ServerProtocol + \todo Write Documentation about HTTP */ /** - * \defgroup ServerProtocolFTP FTP - * \ingroup ServerProtocol - * \todo Write Documentation about FTP + \defgroup ServerProtocolFTP FTP + \ingroup ServerProtocol + \todo Write Documentation about FTP */ /** - * \defgroup ServerProtocolWAIS WAIS - * \ingroup ServerProtocol - * \todo Write Documentation about Wais + \defgroup ServerProtocolWAIS WAIS + \ingroup ServerProtocol + \todo Write Documentation about Wais */ /** - * \defgroup ServerProtocolPassthru Passthru - * \ingroup ServerProtocol - * \todo Write Documentation about Passthru + \defgroup ServerProtocolPassthru Passthru + \ingroup ServerProtocol + \todo Write Documentation about Passthru */ Index: squid3/include/MemPool.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/include/MemPool.h,v retrieving revision 1.10.10.1 retrieving revision 1.10.10.2 diff -u -r1.10.10.1 -r1.10.10.2 --- squid3/include/MemPool.h 23 Jun 2007 01:43:43 -0000 1.10.10.1 +++ squid3/include/MemPool.h 15 Aug 2007 02:32:57 -0000 1.10.10.2 @@ -119,7 +119,9 @@ const char *label; }; -/* Support late binding of pool type for allocator agnostic classes */ +/** + * Support late binding of pool type for allocator agnostic classes + */ class MemAllocatorProxy { public: @@ -137,15 +139,34 @@ size_t size; mutable MemAllocator *theAllocator; }; + /* help for classes */ -/* Put this in the class */ +/** + * Put this in the class + \code + class foo + { + MEMPROXY_CLASS(foo); + } + \endcode + */ #define MEMPROXY_CLASS(CLASS) \ /* TODO change syntax to allow moving into .cci files */ \ inline void *operator new(size_t); \ inline void operator delete(void *); \ static inline MemAllocatorProxy &Pool() -/* put this in the class .h, or .cci as appropriate */ +/** + * Put this in the class .h, or .cci as appropriate + \code + class foo + { + MEMPROXY_CLASS(foo); + } + + MEMPROXY_CLASS_INLINE(foo); + \endcode + */ #define MEMPROXY_CLASS_INLINE(CLASS) \ MemAllocatorProxy& CLASS::Pool() \ { \ Index: squid3/src/ACL.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/ACL.h,v retrieving revision 1.18.10.3 retrieving revision 1.18.10.4 diff -u -r1.18.10.3 -r1.18.10.4 --- squid3/src/ACL.h 6 Aug 2007 08:46:37 -0000 1.18.10.3 +++ squid3/src/ACL.h 15 Aug 2007 02:32:57 -0000 1.18.10.4 @@ -1,6 +1,6 @@ /* - * $Id: ACL.h,v 1.18.10.3 2007/08/06 08:46:37 amosjeffries Exp $ + * $Id: ACL.h,v 1.18.10.4 2007/08/15 02:32:57 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -38,8 +38,9 @@ #include "Array.h" #include "cbdata.h" #include "dlink.h" -/** \todo FIXME: finish splitting out the dependencies here - * - typedefs should not be needed to parse this. +/** + \todo FIXME: finish splitting out the dependencies here + * - typedefs should not be needed to parse this. */ #include "typedefs.h" Index: squid3/src/AuthConfig.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/AuthConfig.h,v retrieving revision 1.3.2.2 retrieving revision 1.3.2.3 diff -u -r1.3.2.2 -r1.3.2.3 --- squid3/src/AuthConfig.h 6 Aug 2007 11:13:47 -0000 1.3.2.2 +++ squid3/src/AuthConfig.h 15 Aug 2007 02:32:57 -0000 1.3.2.3 @@ -1,6 +1,6 @@ /* - * $Id: AuthConfig.h,v 1.3.2.2 2007/08/06 11:13:47 amosjeffries Exp $ + * $Id: AuthConfig.h,v 1.3.2.3 2007/08/15 02:32:57 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -62,19 +62,20 @@ /** * Used by squid to determine whether the auth module has successfully initialised itself with the current configuration. * - * \retval true Authentication Module loaded and running. - * \retval false No Authentication Module loaded. + \retval true Authentication Module loaded and running. + \retval false No Authentication Module loaded. */ virtual bool active() const = 0; - /* new decode API: virtual factory pattern */ /** + * new decode API: virtual factory pattern + \par * Responsible for decoding the passed authentication header, creating or * linking to a AuthUser object and for storing any needed details to complete * authentication in AuthUserRequest::authenticate(). * - * \param proxy_auth Login Pattern to parse. - * \retval * Details needed to authenticate. + \param proxy_auth Login Pattern to parse. + \retval * Details needed to authenticate. */ virtual AuthUserRequest *decode(char const *proxy_auth) = 0; @@ -82,7 +83,8 @@ * squid is finished with this config, release any unneeded resources. * If a singleton, delete will not occur. if not a singleton (future), * delete will occur when no references are held. - * TODO: we need a 'done for reconfigure' and a 'done permanently' concept. + * + \todo we need a 'done for reconfigure' and a 'done permanently' concept. */ virtual void done() = 0; @@ -90,8 +92,8 @@ * The configured function is used to see if the auth module has been given valid * parameters and is able to handle authentication requests. * - * \retval true Authentication Module configured ready for use. - * \retval false Not configured or Configuration Error. + \retval true Authentication Module configured ready for use. + \retval false Not configured or Configuration Error. * No other module functions except Shutdown/Dump/Parse/FreeConfig will be called by Squid. */ virtual bool configured() const = 0; @@ -102,15 +104,15 @@ */ virtual void dump(StoreEntry *, const char *, AuthConfig *) = 0; - /* add headers as needed when challenging for auth */ + /** add headers as needed when challenging for auth */ virtual void fixHeader(AuthUserRequest *, HttpReply *, http_hdr_type, HttpRequest *) = 0; - /* prepare to handle requests */ + /** prepare to handle requests */ virtual void init(AuthConfig *) = 0; - /* expose any/all statistics to a CacheManager */ + /** expose any/all statistics to a CacheManager */ virtual void registerWithCacheManager(CacheManager & manager); - /* parse config options */ + /** parse config options */ virtual void parse(AuthConfig *, int, char *) = 0; - /* the http string id */ + /** the http string id */ virtual const char * type() const = 0; }; Index: squid3/src/AuthUserRequest.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/AuthUserRequest.h,v retrieving revision 1.8.2.5 retrieving revision 1.8.2.6 diff -u -r1.8.2.5 -r1.8.2.6 --- squid3/src/AuthUserRequest.h 6 Aug 2007 11:43:44 -0000 1.8.2.5 +++ squid3/src/AuthUserRequest.h 15 Aug 2007 02:32:57 -0000 1.8.2.6 @@ -1,6 +1,6 @@ /* - * $Id: AuthUserRequest.h,v 1.8.2.5 2007/08/06 11:43:44 amosjeffries Exp $ + * $Id: AuthUserRequest.h,v 1.8.2.6 2007/08/15 02:32:57 amosjeffries Exp $ * * DO NOT MODIFY NEXT 2 LINES: * arch-tag: 674533af-8b21-4641-b71a-74c4639072a0 @@ -54,7 +54,7 @@ }; /** - * \ingroup AuthAPI + \ingroup AuthAPI * This is a short lived structure is the visible aspect of the authentication framework. */ class AuthUserRequest @@ -71,20 +71,20 @@ /** * Used by squid to determine what the next step in performing authentication for a given scheme is. * - * \retval -2 ERROR in the auth module. Cannot determine request direction. - * \retval -1 The auth module needs to send data to an external helper. - * Squid will prepare for a callback on the request and call the AUTHSSTART function. - * \retval 0 The auth module has all the information it needs to perform the authentication and provide a succeed/fail result. - * \retval 1 The auth module needs to send a new challenge to the request originator. - * Squid will return the appropriate status code (401 or 407) and call the registered FixError function to allow the auth module to insert it's challenge. + \retval -2 ERROR in the auth module. Cannot determine request direction. + \retval -1 The auth module needs to send data to an external helper. + * Squid will prepare for a callback on the request and call the AUTHSSTART function. + \retval 0 The auth module has all the information it needs to perform the authentication and provide a succeed/fail result. + \retval 1 The auth module needs to send a new challenge to the request originator. + * Squid will return the appropriate status code (401 or 407) and call the registered FixError function to allow the auth module to insert it's challenge. */ int direction(); /** * Used by squid to determine whether the auth scheme has successfully authenticated the user request. * - * \retval true User has successfully been authenticated. - * \retval false Timeouts on cached credentials have occurred or for any reason the credentials are not valid. + \retval true User has successfully been authenticated. + \retval false Timeouts on cached credentials have occurred or for any reason the credentials are not valid. */ virtual int authenticated() const = 0; @@ -99,8 +99,8 @@ * Called when squid is ready to put the request on hold and wait for a callback from the auth module * when the auth module has performed it's external activities. * - * \param handler Handler to process the callback when its run - * \param data CBDATA for handler + \param handler Handler to process the callback when its run + \param data CBDATA for handler */ virtual void module_start(RH *handler, void *data) = 0; @@ -121,8 +121,11 @@ void start ( RH * handler, void *data); char const * denyMessage (char const * const default_message = NULL); - /* these two are possibly overrideable in future */ + + /** Possibly overrideable in future */ void setDenyMessage (char const *); + + /** Possibly overrideable in future */ char const * getDenyMessage (); size_t refCount() const; @@ -134,8 +137,8 @@ * This function must return a pointer to a NULL terminated string to be used in logging the request. * The string should NOT be allocated each time this function is called. * - * \retval NULL No username/usercode is known. - * \retval * Null-terminated username string. + \retval NULL No username/usercode is known. + \retval * Null-terminated username string. */ char const *username() const; @@ -162,8 +165,11 @@ }; /* AuthUserRequest */ -/// \ingroup AuthAPI -/// \deprecated Use AuthUserRequest::refCount() instead. + +/** + \ingroup AuthAPI + \deprecated Use AuthUserRequest::refCount() instead. + */ extern size_t authenticateRequestRefCount (AuthUserRequest *); /// \ingroup AuthAPI @@ -187,6 +193,7 @@ /// \ingroup AuthAPI extern int authenticateValidateUser(AuthUserRequest *); +/// \todo Drop dead code? or make a debugging option. #if 0 #define AUTHUSERREQUESTUNLOCK(a,b) if(a){(a)->_unlock();debugs(0,0,HERE << "auth_user_request " << a << " was unlocked for " << b); (a)=NULL;} #define AUTHUSERREQUESTLOCK(a,b) { (a)->_lock(); debugs(0,0,HERE << "auth_user_request " << a << " was locked for " << b); } Index: squid3/src/URL.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/URL.h,v retrieving revision 1.1.24.1 retrieving revision 1.1.24.2 diff -u -r1.1.24.1 -r1.1.24.2 --- squid3/src/URL.h 11 Jul 2007 03:14:59 -0000 1.1.24.1 +++ squid3/src/URL.h 15 Aug 2007 02:32:57 -0000 1.1.24.2 @@ -1,6 +1,5 @@ - /* - * $Id: URL.h,v 1.1.24.1 2007/07/11 03:14:59 amosjeffries Exp $ + * $Id: URL.h,v 1.1.24.2 2007/08/15 02:32:57 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -38,9 +37,11 @@ #include "MemPool.h" #include "URLScheme.h" -/** \ingroup POD */ -/** The URL class represents a Uniform Resource Location */ - +/** + \ingroup POD + * + * The URL class represents a Uniform Resource Location + */ class URL { @@ -53,11 +54,11 @@ private: /** - * \par + \par * The scheme of this URL. This has the 'type code' smell about it. * In future we may want to make the methods that dispatch based on * the scheme virtual and have a class per protocol. - * \par + \par * On the other hand, having Protocol as an explicit concept is useful, * see for instance the ACLProtocol acl type. One way to represent this * is to have one prototype URL with no host etc for each scheme, @@ -66,9 +67,9 @@ * a URLScheme class instance for each URLScheme we support, and one URL * class for each manner of treating the scheme : a Hierarchical URL, a * non-hierarchical URL etc. - * \par + \par * Deferring the decision, its a type code for now. RBC 20060507. - * \par + \par * In order to make taking any of these routes easy, scheme is private * and immutable, only settable at construction time, */ Index: squid3/src/authenticate.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/authenticate.h,v retrieving revision 1.14.14.1 retrieving revision 1.14.14.2 diff -u -r1.14.14.1 -r1.14.14.2 --- squid3/src/authenticate.h 6 Aug 2007 05:18:23 -0000 1.14.14.1 +++ squid3/src/authenticate.h 15 Aug 2007 02:32:57 -0000 1.14.14.2 @@ -1,6 +1,5 @@ - /* - * $Id: authenticate.h,v 1.14.14.1 2007/08/06 05:18:23 amosjeffries Exp $ + * $Id: authenticate.h,v 1.14.14.2 2007/08/15 02:32:57 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -39,10 +38,13 @@ class AuthUser; /** - * \ingroup AuthAPI + \ingroup AuthAPI + * * This is used to link auth_users into the username cache. * Because some schemes may link in aliases to a user, * the link is not part of the AuthUser structure itself. + * + \todo Inheritance in a struct? this should be a class. */ struct AuthUserHashPointer : public hash_link { @@ -66,23 +68,38 @@ class AuthScheme; -/* authenticate.c authenticate scheme routines typedefs */ -/* TODO: this should be a generic cachemgr API type ? */ +/** + \ingroup AuthAPI + \todo this should be a generic cachemgr API type ? + */ typedef void AUTHSSTATS(StoreEntry *); -/* subsumed by the C++ interface */ +/** + \ingroup AuthAPI + * subsumed by the C++ interface + \todo does 'subsumed' mean deprecated use a C++ API call? + */ extern void authenticateAuthUserMerge(auth_user_t *, auth_user_t *); +/// \ingroup AuthAPI extern void authenticateInit(authConfig *); +/// \ingroup AuthAPI extern void authenticateRegisterWithCacheManager(authConfig * config, CacheManager & manager); +/// \ingroup AuthAPI extern void authenticateShutdown(void); +/// \ingroup AuthAPI extern int authenticateAuthUserInuse(auth_user_t * auth_user); +/// \ingroup AuthAPI extern void authenticateFreeProxyAuthUserACLResults(void *data); +/// \ingroup AuthAPI extern int authenticateActiveSchemeCount(void); +/// \ingroup AuthAPI extern int authenticateSchemeCount(void); +/// \ingroup AuthAPI extern void authenticateUserCacheRestart(void); +/// \ingroup AuthAPI extern void authenticateOnCloseConnection(ConnStateData * conn); #endif /* SQUID_AUTHENTICATE_H */ Index: squid3/src/cbdata.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/cbdata.h,v retrieving revision 1.1.22.3 retrieving revision 1.1.22.4 diff -u -r1.1.22.3 -r1.1.22.4 --- squid3/src/cbdata.h 10 Aug 2007 00:12:56 -0000 1.1.22.3 +++ squid3/src/cbdata.h 15 Aug 2007 02:32:57 -0000 1.1.22.4 @@ -1,5 +1,5 @@ /* - * $Id: cbdata.h,v 1.1.22.3 2007/08/10 00:12:56 amosjeffries Exp $ + * $Id: cbdata.h,v 1.1.22.4 2007/08/15 02:32:57 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -431,7 +431,7 @@ #define CBDATA_INIT_TYPE_FREECB(type, free_func) (CBDATA_##type ? CBDATA_UNKNOWN : (CBDATA_##type = cbdataInternalAddType(CBDATA_##type, #type, sizeof(type), free_func))) /** - * \ingroup CBDATA + \ingroup CBDATA * * A generic wrapper for passing objects through cbdata. * Use this when you need to pass callback data to a blocking @@ -454,7 +454,7 @@ * done by store_swapout - it gives a wrapped StoreEntry to StoreIO as the * object to be given to the callbacks. That needs to be fully cleaned up! * - RBC 20060820 - * \todo CODE: make this a private field. + \todo CODE: make this a private field. */ void *data; /* the wrapped data */ private: Index: squid3/src/clientStream.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/clientStream.cc,v retrieving revision 1.11.2.4 retrieving revision 1.11.2.5 diff -u -r1.11.2.4 -r1.11.2.5 --- squid3/src/clientStream.cc 10 Aug 2007 00:12:56 -0000 1.11.2.4 +++ squid3/src/clientStream.cc 15 Aug 2007 02:32:58 -0000 1.11.2.5 @@ -1,6 +1,6 @@ /* - * $Id: clientStream.cc,v 1.11.2.4 2007/08/10 00:12:56 amosjeffries Exp $ + * $Id: clientStream.cc,v 1.11.2.5 2007/08/15 02:32:58 amosjeffries Exp $ * * DEBUG: section 87 Client-side Stream routines. * AUTHOR: Robert Collins @@ -102,7 +102,7 @@ return; \endcode * - * \todo rather than each node undeleting the next, have a clientStreamDelete that walks the list + \todo rather than each node undeleting the next, have a clientStreamDelete that walks the list. */ /// \ingroup ClientStreamInternal Index: squid3/src/fqdncache.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fqdncache.cc,v retrieving revision 1.19.2.2 retrieving revision 1.19.2.3 diff -u -r1.19.2.2 -r1.19.2.3 --- squid3/src/fqdncache.cc 10 Aug 2007 00:12:56 -0000 1.19.2.2 +++ squid3/src/fqdncache.cc 15 Aug 2007 02:32:58 -0000 1.19.2.3 @@ -1,5 +1,5 @@ /* - * $Id: fqdncache.cc,v 1.19.2.2 2007/08/10 00:12:56 amosjeffries Exp $ + * $Id: fqdncache.cc,v 1.19.2.3 2007/08/15 02:32:58 amosjeffries Exp $ * * DEBUG: section 35 FQDN Cache * AUTHOR: Harvest Derived @@ -277,7 +277,8 @@ } /** - * \ingroup FQDNCacheInternal + \ingroup FQDNCacheInternal + * * Create blank fqdncache_entry */ static fqdncache_entry * @@ -308,7 +309,8 @@ } /** - * \ingroup FQDNCacheInternal + \ingroup FQDNCacheInternal + * * Walks down the pending list, calling handlers */ static void @@ -483,7 +485,8 @@ /** - * \ingroup FQDNCacheAPI + \ingroup FQDNCacheAPI + * * Callback for handling DNS results. */ static void @@ -514,13 +517,13 @@ } /** - * \ingroup FQDNCacheAPI + \ingroup FQDNCacheAPI * - * \param addr IP address of domain to resolve. - * \param handler A pointer to the function to be called when + \param addr IP address of domain to resolve. + \param handler A pointer to the function to be called when * the reply from the FQDN cache * (or the DNS if the FQDN cache misses) - * \param handlerData Information that is passed to the handler + \param handlerData Information that is passed to the handler * and does not affect the FQDN cache. */ void @@ -588,7 +591,8 @@ } /** - * \ingroup FQDNCacheAPI + \ingroup FQDNCacheAPI + * * Initialize the fqdncache. * Called after IP cache initialization. */ @@ -631,14 +635,15 @@ } /** - * \ingroup FQDNCacheAPI + \ingroup FQDNCacheAPI + * * Is different in that it only checks if an entry exists in * it's data-structures and does not by default contact the * DNS, unless this is requested, by setting the flags * to FQDN_LOOKUP_IF_MISS. * - * \param addr address of the FQDN being resolved - * \param flags values are NULL or FQDN_LOOKUP_IF_MISS. default is NULL. + \param addr address of the FQDN being resolved + \param flags values are NULL or FQDN_LOOKUP_IF_MISS. default is NULL. * */ const char * @@ -689,7 +694,8 @@ /** - * \ingroup FQDNCacheInternal + \ingroup FQDNCacheInternal + * * Process objects list */ void @@ -812,7 +818,8 @@ } /** - * \ingroup FQDNCacheAPI + \ingroup FQDNCacheAPI + * * Recalculate FQDN cache size upon reconfigure. * Is called to clear the FQDN cache's data structures, * cancel all pending requests. @@ -828,9 +835,15 @@ } /** - * \ingroup FQDNCacheAPI - * adds a "static" entry from /etc/hosts. the worldist is to be - * managed by the caller, including pointed-to strings + \ingroup FQDNCacheAPI + * + * Adds a "static" entry from /etc/hosts. + \par + * The worldist is to be managed by the caller, + * including pointed-to strings + * + \param addr FQDN name to be added. + \param hostnames ?? */ void fqdncacheAddEntryFromHosts(char *addr, wordlist * hostnames) Index: squid3/src/ipcache.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/ipcache.cc,v retrieving revision 1.20.2.2 retrieving revision 1.20.2.3 diff -u -r1.20.2.2 -r1.20.2.3 --- squid3/src/ipcache.cc 10 Aug 2007 00:12:56 -0000 1.20.2.2 +++ squid3/src/ipcache.cc 15 Aug 2007 02:32:58 -0000 1.20.2.3 @@ -1,6 +1,6 @@ /* - * $Id: ipcache.cc,v 1.20.2.2 2007/08/10 00:12:56 amosjeffries Exp $ + * $Id: ipcache.cc,v 1.20.2.3 2007/08/15 02:32:58 amosjeffries Exp $ * * DEBUG: section 14 IP Cache * AUTHOR: Harvest Derived @@ -42,10 +42,10 @@ #include "wordlist.h" /** - * \defgroup IPCacheAPI IP Cache API - * \ingroup Components - * \section Introduction Introduction - * \par + \defgroup IPCacheAPI IP Cache API + \ingroup Components + \section Introduction Introduction + \par * The IP cache is a built-in component of squid providing * Hostname to IP-Number translation functionality and managing * the involved data-structures. Efficiency concerns require @@ -57,12 +57,13 @@ */ /** - * \defgroup IPCacheInternal IP Cache Internals - * \ingroup IPCacheAPI - * \todo when IP cache is provided as a class. These sub-groups will be obsolete + \defgroup IPCacheInternal IP Cache Internals + \ingroup IPCacheAPI + \todo when IP cache is provided as a class. These sub-groups will be obsolete * for now they are used to seperate the public and private functions. * with the private ones all being in IPCachInternal and public in IPCacheAPI - * \section InternalOperation Internal Operation + * + \section InternalOperation Internal Operation * * Internally, the execution flow is as follows: On a miss, * ipcache_getnbhostbyname checks whether a request for @@ -82,7 +83,8 @@ typedef struct _ipcache_entry ipcache_entry; /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI + * * The data structure used for storing name-address mappings * is a small hashtable (static hash_table *ip_table), * where structures of type ipcache_entry whose most @@ -183,7 +185,8 @@ } /** - * \ingroup IPCacheInternal + \ingroup IPCacheInternal + * * removes the given ipcache entry */ static void @@ -255,7 +258,8 @@ } /** - * \ingroup IPCacheInternal + \ingroup IPCacheInternal + * * purges entries added from /etc/hosts (or whatever). */ static void @@ -283,7 +287,8 @@ } /** - * \ingroup IPCacheInternal + \ingroup IPCacheInternal + * * create blank ipcache_entry */ static ipcache_entry * @@ -314,7 +319,8 @@ } /** - * \ingroup IPCacheInternal + \ingroup IPCacheInternal + * * walks down the pending list, calling handlers */ static void @@ -564,12 +570,12 @@ } /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI * - * \param name Host to resolve. - * \param handler Pointer to the function to be called when the reply + \param name Host to resolve. + \param handler Pointer to the function to be called when the reply * from the IP cache (or the DNS if the IP cache misses) - * \param handlerData Information that is passed to the handler and does not affect the IP cache. + \param handlerData Information that is passed to the handler and does not affect the IP cache. */ void ipcache_nbgethostbyname(const char *name, IPH * handler, void *handlerData) @@ -638,7 +644,8 @@ } /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI + * * Initialize the ipcache. * Is called from mainInitialize() after disk initialization * and prior to the reverse FQDNCache initialization @@ -683,18 +690,19 @@ } /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI + * * Is different from ipcache_nbgethostbyname in that it only checks * if an entry exists in the cache and does not by default contact the DNS, * unless this is requested, by setting the flags. * - * \param name Host name to resolve. - * \param flags Default is NULL, set to IP_LOOKUP_IF_MISS + \param name Host name to resolve. + \param flags Default is NULL, set to IP_LOOKUP_IF_MISS * to explicitly perform DNS lookups. * - * \retval NULL An error occured during lookup - * \retval NULL No results available in cache and no lookup specified - * \retval * Pointer to the ipcahce_addrs structure containing the lookup results + \retval NULL An error occured during lookup + \retval NULL No results available in cache and no lookup specified + \retval * Pointer to the ipcahce_addrs structure containing the lookup results */ const ipcache_addrs * ipcache_gethostbyname(const char *name, int flags) @@ -758,7 +766,8 @@ } /** - * \ingroup IPCacheInternal + \ingroup IPCacheInternal + * * process objects list */ void @@ -920,7 +929,8 @@ } /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI + * * Marks the given address as BAD and calls ipcacheCycleAddr to * advance the current pointer to the next OK address. */ @@ -1010,7 +1020,8 @@ } /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI + * * Recalculate IP cache size upon reconfigure. * Is called to clear the IPCache's data structures, * cancel all pending requests. @@ -1026,14 +1037,15 @@ } /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI + * * Adds a "static" entry from /etc/hosts * - * \param name Hostname to be linked with IP - * \param ipaddr IP Address to be cached. + \param name Hostname to be linked with IP + \param ipaddr IP Address to be cached. * - * \retval 0 Success. - * \retval 1 IP address is invalid or other error. + \retval 0 Success. + \retval 1 IP address is invalid or other error. */ int ipcacheAddEntryFromHosts(const char *name, const char *ipaddr) @@ -1080,7 +1092,8 @@ #ifdef SQUID_SNMP /** - * \ingroup IPCacheAPI + \ingroup IPCacheAPI + * * The function to return the ip cache statistics to via SNMP */ variable_list * Index: squid3/src/fs/aufs/StoreFSaufs.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fs/aufs/StoreFSaufs.cc,v retrieving revision 1.2.24.2 retrieving revision 1.2.24.3 diff -u -r1.2.24.2 -r1.2.24.3 --- squid3/src/fs/aufs/StoreFSaufs.cc 12 Jul 2007 04:18:03 -0000 1.2.24.2 +++ squid3/src/fs/aufs/StoreFSaufs.cc 15 Aug 2007 02:32:58 -0000 1.2.24.3 @@ -1,6 +1,6 @@ /* - * $Id: StoreFSaufs.cc,v 1.2.24.2 2007/07/12 04:18:03 amosjeffries Exp $ + * $Id: StoreFSaufs.cc,v 1.2.24.3 2007/08/15 02:32:58 amosjeffries Exp $ * * DEBUG: section 47 Store Directory Routines * AUTHOR: Robert Collins @@ -40,8 +40,8 @@ #include "DiskIO/DiskIOModule.h" /** - * \defgroup AUFS AUFS Storage Filesystem (UFS Based) - * \ingroup UFS, FileSystems + \defgroup AUFS AUFS Storage Filesystem (UFS Based) + \ingroup UFS, FileSystems */ /// \ingroup AUFS Index: squid3/src/fs/coss/StoreFScoss.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fs/coss/StoreFScoss.h,v retrieving revision 1.3.14.1 retrieving revision 1.3.14.2 diff -u -r1.3.14.1 -r1.3.14.2 --- squid3/src/fs/coss/StoreFScoss.h 12 Jul 2007 04:18:03 -0000 1.3.14.1 +++ squid3/src/fs/coss/StoreFScoss.h 15 Aug 2007 02:32:58 -0000 1.3.14.2 @@ -1,6 +1,6 @@ /* - * $Id: StoreFScoss.h,v 1.3.14.1 2007/07/12 04:18:03 amosjeffries Exp $ + * $Id: StoreFScoss.h,v 1.3.14.2 2007/08/15 02:32:58 amosjeffries Exp $ * * SQUID Web Proxy Cache http://www.squid-cache.org/ * ---------------------------------------------------------- @@ -37,8 +37,8 @@ #include "StoreFileSystem.h" /** - * \defgroup COSS COSS Storage Filesystem - * \ingroup FileSystems + \defgroup COSS COSS Storage Filesystem + \ingroup FileSystems */ /// \ingroup COSS Index: squid3/src/fs/coss/store_coss.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fs/coss/store_coss.h,v retrieving revision 1.14.10.3 retrieving revision 1.14.10.4 diff -u -r1.14.10.3 -r1.14.10.4 --- squid3/src/fs/coss/store_coss.h 15 Aug 2007 01:00:13 -0000 1.14.10.3 +++ squid3/src/fs/coss/store_coss.h 15 Aug 2007 02:32:58 -0000 1.14.10.4 @@ -7,11 +7,15 @@ #define COSS_MEMBUF_SZ 1048576 #endif -/* Note that swap_filen in sio/e are actually disk offsets too! */ +/** \note swap_filen in sio/e are actually disk offsets too! */ -/* What we're doing in storeCossAllocate() */ +/** What we're doing in storeCossAllocate() */ #define COSS_ALLOC_NOTIFY 0 + +/** What we're doing in storeCossAllocate() */ #define COSS_ALLOC_ALLOCATE 1 + +/** What we're doing in storeCossAllocate() */ #define COSS_ALLOC_REALLOC 2 class CossSwapDir; @@ -41,8 +45,9 @@ /// \ingroup COSS struct _cossindex { - /* Note: the dlink_node MUST be the first member of the structure. - * This member is later pointer typecasted to coss_index_node *. + /** + \note The dlink_node MUST be the first member of the structure. + * This member is later pointer typecasted to coss_index_node *. */ dlink_node node; }; @@ -50,7 +55,7 @@ /** - * \ingroup COSS + \ingroup COSS * Per-storeiostate info */ class CossState : public StoreIOState @@ -97,7 +102,7 @@ /** - * \ingroup COSS + \ingroup COSS * Whether the coss system has been setup or not */ extern int coss_initialised; Index: squid3/src/fs/diskd/StoreFSdiskd.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fs/diskd/StoreFSdiskd.cc,v retrieving revision 1.2.24.2 retrieving revision 1.2.24.3 diff -u -r1.2.24.2 -r1.2.24.3 --- squid3/src/fs/diskd/StoreFSdiskd.cc 12 Jul 2007 04:18:03 -0000 1.2.24.2 +++ squid3/src/fs/diskd/StoreFSdiskd.cc 15 Aug 2007 02:32:58 -0000 1.2.24.3 @@ -1,6 +1,6 @@ /* - * $Id: StoreFSdiskd.cc,v 1.2.24.2 2007/07/12 04:18:03 amosjeffries Exp $ + * $Id: StoreFSdiskd.cc,v 1.2.24.3 2007/08/15 02:32:58 amosjeffries Exp $ * * DEBUG: section 47 Store Directory Routines * AUTHOR: Robert Collins @@ -40,8 +40,8 @@ #include "DiskIO/DiskIOModule.h" /** - * \defgroup diskd diskd Storage Filesystem (UFS Based) - * \ingroup FileSystems, UFS + \defgroup diskd diskd Storage Filesystem (UFS Based) + \ingroup FileSystems, UFS */ /// \ingroup diskd Index: squid3/src/fs/null/StoreFSnull.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fs/null/StoreFSnull.h,v retrieving revision 1.1.32.1 retrieving revision 1.1.32.2 diff -u -r1.1.32.1 -r1.1.32.2 --- squid3/src/fs/null/StoreFSnull.h 12 Jul 2007 04:18:03 -0000 1.1.32.1 +++ squid3/src/fs/null/StoreFSnull.h 15 Aug 2007 02:32:58 -0000 1.1.32.2 @@ -1,6 +1,6 @@ /* - * $Id: StoreFSnull.h,v 1.1.32.1 2007/07/12 04:18:03 amosjeffries Exp $ + * $Id: StoreFSnull.h,v 1.1.32.2 2007/08/15 02:32:58 amosjeffries Exp $ * * SQUID Web Proxy Cache http://www.squid-cache.org/ * ---------------------------------------------------------- @@ -37,8 +37,8 @@ #include "squid.h" /** - * \defgroup NULL Memory-Only Filesystem - * \ingroup FileSystems + \defgroup NULL Memory-Only Filesystem + \ingroup FileSystems * * Non-Disk storage system. cache_dir contents are held fully within RAM. */ @@ -56,8 +56,10 @@ virtual SwapDir *createSwapDir(); virtual void done(); virtual void setup(); - /* Not implemented */ + + /** Not implemented */ StoreFSnull (StoreFSnull const &); + StoreFSnull &operator=(StoreFSnull const &); private: Index: squid3/src/fs/ufs/StoreFSufs.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fs/ufs/StoreFSufs.h,v retrieving revision 1.5.10.2 retrieving revision 1.5.10.3 diff -u -r1.5.10.2 -r1.5.10.3 --- squid3/src/fs/ufs/StoreFSufs.h 12 Jul 2007 04:18:03 -0000 1.5.10.2 +++ squid3/src/fs/ufs/StoreFSufs.h 15 Aug 2007 02:32:58 -0000 1.5.10.3 @@ -1,6 +1,6 @@ /* - * $Id: StoreFSufs.h,v 1.5.10.2 2007/07/12 04:18:03 amosjeffries Exp $ + * $Id: StoreFSufs.h,v 1.5.10.3 2007/08/15 02:32:58 amosjeffries Exp $ * * SQUID Web Proxy Cache http://www.squid-cache.org/ * ---------------------------------------------------------- @@ -39,12 +39,12 @@ #include "DiskIO/DiskIOModule.h" /** - * \defgroup UFS UFS Storage Filesystem - * \ingroup FileSystems + \defgroup UFS UFS Storage Filesystem + \ingroup FileSystems */ /** - * \ingroup UFS, FileSystems + \ingroup UFS, FileSystems * * Core UFS class. This template provides compile time aliases for * ufs/aufs/diskd to ease configuration conversion - each becomes a @@ -64,7 +64,7 @@ virtual SwapDir *createSwapDir(); virtual void done(); virtual void setup(); - /* Not implemented */ + /** Not implemented */ StoreFSufs (StoreFSufs const &); StoreFSufs &operator=(StoreFSufs const &); Index: squid3/src/fs/ufs/ufscommon.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fs/ufs/ufscommon.h,v retrieving revision 1.9.10.4 retrieving revision 1.9.10.5 diff -u -r1.9.10.4 -r1.9.10.5 --- squid3/src/fs/ufs/ufscommon.h 15 Aug 2007 01:00:14 -0000 1.9.10.4 +++ squid3/src/fs/ufs/ufscommon.h 15 Aug 2007 02:32:59 -0000 1.9.10.5 @@ -1,6 +1,6 @@ /* - * $Id: ufscommon.h,v 1.9.10.4 2007/08/15 01:00:14 amosjeffries Exp $ + * $Id: ufscommon.h,v 1.9.10.5 2007/08/15 02:32:59 amosjeffries Exp $ * * SQUID Web Proxy Cache http://www.squid-cache.org/ * ---------------------------------------------------------- @@ -148,10 +148,11 @@ #include "RefCount.h" #include "DiskIO/IORequestor.h" -/** UFS dir specific IO calls +/** + * UFS dir specific IO calls * - * \todo This should be whittled away - DiskIOModule should be providing the - * entire needed api. + \todo This should be whittled away. + * DiskIOModule should be providing the entire needed API. */ class DiskIOStrategy; @@ -353,7 +354,7 @@ int SwapLogEntries(); void Close() { - if(log){ + if(log){ fclose(log); log = NULL; } @@ -370,12 +371,17 @@ RebuildState(RefCount sd); ~RebuildState(); - /* Iterator API - garh, wrong place */ - /* callback the client when a new StoreEntry is available + /** \todo Iterator API - garh, wrong place */ + /** + * callback the client when a new StoreEntry is available * or an error occurs */ virtual void next(void (callback)(void *cbdata), void *cbdata); - /** \retval true if a new StoreEntry is immediately available */ + + /** + \retval true if a new StoreEntry is immediately available + \retval false if a new StoreEntry is NOT immediately available + */ virtual bool next(); virtual bool error() const; virtual bool isDone() const;