From: Amos Jeffries Date: Fri, 28 Sep 2018 15:33:12 +0000 (+0000) Subject: Docs: make doxygen happier and fix some comments (#293) X-Git-Tag: M-staged-PR293 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f439fbd23c5765aaa2337923fd01482ed1edac56;p=thirdparty%2Fsquid.git Docs: make doxygen happier and fix some comments (#293) * Update some code syntax for doxygen's naive parser. * Fix duplicate section IDs in doxygen comments. * Fix some doxygen markup typos. * Remove an unnecessary todo. No logical changes. --- diff --git a/doc/Programming-Guide/DelayPools.dox b/doc/Programming-Guide/DelayPools.dox index ebdc90363e..2053a493a0 100644 --- a/doc/Programming-Guide/DelayPools.dox +++ b/doc/Programming-Guide/DelayPools.dox @@ -9,7 +9,7 @@ /** \page 10_DelayPools Delay Pools -\section Introduction Introduction +\section DelayPoolsIntro Introduction \par A DelayPool is a Composite used to manage bandwidth for any request assigned to the pool by an access expression. DelayId's are a used diff --git a/include/rfc1738.h b/include/rfc1738.h index 9b55b4db7e..e5ec273a06 100644 --- a/include/rfc1738.h +++ b/include/rfc1738.h @@ -25,15 +25,15 @@ extern "C" { #define RFC1738_ESCAPE_UNESCAPED (RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_CTRLS|RFC1738_ESCAPE_NOPERCENT) /** - * \group rfc1738 RFC 1738 URL-escaping library + * RFC 1738 URL-escaping * * Public API is formed of a triplet of encode functions mapping to the rfc1738_do_encode() engine. * * ASCII characters are split into four groups: - * \item SAFE Characters which are safe to occur in any URL. For example A,B,C - * \item CTRLS Binary control codes. Dangerous to include in URLs. - * \item UNSAFE Characters which are completely usafe to occur in any URL. For example; backspace, tab, space, newline. - * \item RESERVED Characters which are reserved for special meaning and may only occur in certain parts of a URL. + * \li SAFE Characters which are safe to occur in any URL. For example A,B,C + * \li CTRLS Binary control codes. Dangerous to include in URLs. + * \li UNSAFE Characters which are completely usafe to occur in any URL. For example; backspace, tab, space, newline. + * \li RESERVED Characters which are reserved for special meaning and may only occur in certain parts of a URL. * * Returns a static buffer containing the RFC 1738 compliant, escaped version of the given url. * diff --git a/lib/smblib/smblib-api.c b/lib/smblib/smblib-api.c index d0ffa333f6..f805392a92 100644 --- a/lib/smblib/smblib-api.c +++ b/lib/smblib/smblib-api.c @@ -292,7 +292,7 @@ int SMBapi_NetSetUserInfo(SMB_Tree_Handle tree, char *user, if (pad_api_name == TRUE) /* Pad to a word boundary */ p = p + 1; - /* SSVAL(p, 0, 65000); /* Check the result */ + /* SSVAL(p, 0, 65000); */ /* Check the result */ SSVAL(p, 0, SMB_LMapi_SetUserInfo); /* The api call */ p = p + 2; diff --git a/src/StoreFileSystem.h b/src/StoreFileSystem.h index a55620739b..afe7c4e68a 100644 --- a/src/StoreFileSystem.h +++ b/src/StoreFileSystem.h @@ -17,7 +17,7 @@ /** \defgroup FileSystems Storage Filesystems * - \section Introduction Introduction + \section FileSystemsIntroduction Introduction \par * Traditionally, Squid has always used the Unix filesystem (\link UFS UFS\endlink) * to store cache objects on disk. Over the years, the diff --git a/src/base/AsyncJobs.dox b/src/base/AsyncJobs.dox index 57370c9519..70bc17c923 100644 --- a/src/base/AsyncJobs.dox +++ b/src/base/AsyncJobs.dox @@ -10,14 +10,14 @@ \defgroup AsyncJobs Asynchronous Jobs \ingroup Components -\section Terminology Terminology +\section AsyncJobsTerminology Terminology - \b Job: an AsyncJob object. - \b Creator: the code creating the job. Usually the Initiator. - \b Start: the act of calling AsyncJob::Start with a job pointer. - \b Initiator: the code starting the job. Usually the Creator. -\section Life Typical life cycle +\section AsyncJobsLifecycle Typical life cycle -# Creator creates and initializes a job. -# If Initiator expects to communicate with the job after start, @@ -50,7 +50,7 @@ Keep in mind that you have no async debugging, cleanup, and protections until you call AsyncJob::Start with a job pointer. -\section Rules Basic rules +\section AsyncJobsBasicRules Basic rules - To start a job, use AsyncJob::Start. Do not start the same job more than once. diff --git a/src/cbdata.h b/src/cbdata.h index a6ae915b27..3fee0c7b1b 100644 --- a/src/cbdata.h +++ b/src/cbdata.h @@ -12,7 +12,7 @@ /** \page CBDATA Callback Data Allocator API - \section Introduction + \section CbDataIntro Introduction \par Squid's extensive use of callback functions makes it very diff --git a/src/clientStream.h b/src/clientStream.h index ea2930f543..385bfa9950 100644 --- a/src/clientStream.h +++ b/src/clientStream.h @@ -17,7 +17,7 @@ /** \defgroup ClientStreamAPI Client Streams API \ingroup Components - \section Introduction Introduction + \section ClientStreamIntroduction Introduction \par * A ClientStream implements a unidirectional, non-blocking, * pull pipeline. They allow code to be inserted into the diff --git a/src/clients/Client.h b/src/clients/Client.h index 6b8548d3a0..f706e68295 100644 --- a/src/clients/Client.h +++ b/src/clients/Client.h @@ -56,7 +56,7 @@ public: /// abnormal data transfer termination /// \retval true the transaction will be terminated (abortAll called) - /// \reval false the transaction will survive + /// \retval false the transaction will survive virtual bool abortOnData(const char *reason); /// a hack to reach HttpStateData::orignal_request diff --git a/src/errorpage.cc b/src/errorpage.cc index c81e0a9c01..17d2ecf9fc 100644 --- a/src/errorpage.cc +++ b/src/errorpage.cc @@ -40,7 +40,7 @@ \defgroup ErrorPageInternal Error Page Internals \ingroup ErrorPageAPI * - \section Abstract Abstract: + \section ErrorPagesAbstract Abstract: * These routines are used to generate error messages to be * sent to clients. The error type is used to select between * the various message formats. (formats are stored in the diff --git a/src/fqdncache.cc b/src/fqdncache.cc index e39f37f4f4..d54c82fa76 100644 --- a/src/fqdncache.cc +++ b/src/fqdncache.cc @@ -30,7 +30,7 @@ /** \defgroup FQDNCacheAPI FQDN Cache API \ingroup Components - \section Introduction Introduction + \section FQDNCacheIntroduction Introduction \par * The FQDN cache is a built-in component of squid providing * Hostname to IP-Number translation functionality and managing @@ -38,8 +38,6 @@ * mechanisms that allow non-blocking access to these mappings. * The FQDN cache usually doesn't block on a request except for * special cases where this is desired (see below). - * - \todo FQDN Cache should have its own API *.h file. */ /** diff --git a/src/fs/rock/RockRebuild.cc b/src/fs/rock/RockRebuild.cc index 4bb062ed3b..d34864ba6a 100644 --- a/src/fs/rock/RockRebuild.cc +++ b/src/fs/rock/RockRebuild.cc @@ -30,7 +30,7 @@ CBDATA_NAMESPACED_CLASS_INIT(Rock, Rebuild); \defgroup RockFsRebuild Rock Store Rebuild \ingroup Filesystems * - \section Overview Overview + \section RockFsRebuildOverview Overview * Several layers of information are manipualted during the rebuild: \par * Store Entry: Response message plus all the metainformation associated with diff --git a/src/http/one/Parser.h b/src/http/one/Parser.h index 0410b290fa..f1f5021543 100644 --- a/src/http/one/Parser.h +++ b/src/http/one/Parser.h @@ -33,8 +33,8 @@ enum ParseState { * Works on a raw character I/O buffer and tokenizes the content into * the major CRLF delimited segments of an HTTP/1 procotol message: * - * \item first-line (request-line / simple-request / status-line) - * \item mime-header 0*( header-name ':' SP field-value CRLF) + * \li first-line (request-line / simple-request / status-line) + * \li mime-header 0*( header-name ':' SP field-value CRLF) */ class Parser : public RefCountable { diff --git a/src/http/one/RequestParser.h b/src/http/one/RequestParser.h index 3ff9df3b82..62c9327faf 100644 --- a/src/http/one/RequestParser.h +++ b/src/http/one/RequestParser.h @@ -24,8 +24,8 @@ namespace One { * Works on a raw character I/O buffer and tokenizes the content into * the major CRLF delimited segments of an HTTP/1 request message: * - * \item request-line (method, URL, protocol, version) - * \item mime-header (set of RFC2616 syntax header fields) + * \li request-line (method, URL, protocol, version) + * \li mime-header (set of RFC2616 syntax header fields) */ class RequestParser : public Http1::Parser { diff --git a/src/http/one/ResponseParser.h b/src/http/one/ResponseParser.h index d751eedf4e..92e134919d 100644 --- a/src/http/one/ResponseParser.h +++ b/src/http/one/ResponseParser.h @@ -23,8 +23,8 @@ namespace One { * Works on a raw character I/O buffer and tokenizes the content into * the major CRLF delimited segments of an HTTP/1 respone message: * - * \item status-line (version SP status SP reash-phrase) - * \item mime-header (set of RFC2616 syntax header fields) + * \li status-line (version SP status SP reash-phrase) + * \li mime-header (set of RFC2616 syntax header fields) */ class ResponseParser : public Http1::Parser { diff --git a/src/ipcache.cc b/src/ipcache.cc index 689a57c898..650d5289cf 100644 --- a/src/ipcache.cc +++ b/src/ipcache.cc @@ -33,7 +33,7 @@ /** \defgroup IPCacheAPI IP Cache API \ingroup Components - \section Introduction Introduction + \section IpcacheIntroduction Introduction \par * The IP cache is a built-in component of squid providing * Hostname to IP-Number translation functionality and managing diff --git a/src/security/forward.h b/src/security/forward.h index 7bf3f0e194..666c92d826 100644 --- a/src/security/forward.h +++ b/src/security/forward.h @@ -83,7 +83,7 @@ class CertError; typedef CbDataList CertErrors; #if USE_OPENSSL -CtoCpp1(X509_free, X509 *) +CtoCpp1(X509_free, X509 *); typedef Security::LockingPointer > CertPointer; #elif USE_GNUTLS typedef std::shared_ptr CertPointer; @@ -92,10 +92,10 @@ typedef std::shared_ptr CertPointer; #endif #if USE_OPENSSL -CtoCpp1(X509_CRL_free, X509_CRL *) +CtoCpp1(X509_CRL_free, X509_CRL *); typedef Security::LockingPointer > CrlPointer; #elif USE_GNUTLS -CtoCpp1(gnutls_x509_crl_deinit, gnutls_x509_crl_t) +CtoCpp1(gnutls_x509_crl_deinit, gnutls_x509_crl_t); typedef Security::LockingPointer CrlPointer; #else typedef void *CrlPointer; diff --git a/src/ssl/ErrorDetailManager.h b/src/ssl/ErrorDetailManager.h index 875d42480c..f15b52b813 100644 --- a/src/ssl/ErrorDetailManager.h +++ b/src/ssl/ErrorDetailManager.h @@ -68,7 +68,7 @@ public: * Retrieve error details for an error. This method examine the Accept-Language * of the request to retrieve the error details for requested language else return * the default error details. - * \param vale the error code + * \param value the error code * \param request the current HTTP request. * \param entry where to store error details * \return true on success, false otherwise diff --git a/src/ssl/cert_validate_message.h b/src/ssl/cert_validate_message.h index 020f42d58f..0bbdb12617 100644 --- a/src/ssl/cert_validate_message.h +++ b/src/ssl/cert_validate_message.h @@ -70,9 +70,12 @@ public: /** * This class is responsible for composing or parsing messages destined to - * or comming from a cert validator helper. + * or comming from a certificate validation helper. * The messages format is: - * response/request-code SP body-length SP [key=value ...] \x01 +\verbatim + response/request-code SP body-length SP [key=value ...] EOL +\endverbatim + * \note EOL for this interface is character 0x01 */ class CertValidationMsg : public CrtdMessage {