From 5943a9c0f512b541f4a24caac4e700c506eb4ce9 Mon Sep 17 00:00:00 2001 From: nishi Date: Fri, 5 Apr 2024 15:59:42 +0000 Subject: [PATCH] document generating git-svn-id: file:///raid/svn-main/nishi-libw3/trunk@271 d27a3e52-49c5-7645-884c-6793ebffc270 --- Doxyfile | 5 +++++ Library/W3Core.h | 57 +++++++++++++++++++++++++++++++++++++++++++----- Library/W3FTP.h | 29 ++++++++++++++++++++++++ Library/W3HTTP.h | 10 +++++++++ Library/W3IRC.h | 53 ++++++++++++++++++++++++++++++++++++++++++++ Library/W3NNTP.h | 17 +++++++++++++++ Library/W3POP3.h | 30 +++++++++++++++++++++++++ Library/W3Tag.h | 24 ++++++++++++++++++++ Library/W3Tcl.h | 10 +++++++++ Library/W3URL.h | 45 ++++++++++++++++++++++++++++++++++++++ Library/W3Util.h | 9 ++++++++ 11 files changed, 284 insertions(+), 5 deletions(-) diff --git a/Doxyfile b/Doxyfile index 9343f56..4eef145 100644 --- a/Doxyfile +++ b/Doxyfile @@ -18,3 +18,8 @@ HTML_EXTRA_STYLESHEET = doxygen-theme/doxygen-awesome.css HTML_COLORSTYLE = LIGHT PROJECT_LOGO = w3.png PROJECT_BRIEF = WWW Library +GENERATE_MAN = YES +GENERATE_LATEX = NO +EXAMPLE_PATH = Example +EXAMPLE_RECURSIVE = YES +EXAMPLE_PATTERNS = *.c diff --git a/Library/W3Core.h b/Library/W3Core.h index b7539a0..14e6b38 100644 --- a/Library/W3Core.h +++ b/Library/W3Core.h @@ -47,6 +47,10 @@ extern "C" { #include "W3Version.h" +/** + * @warning + * This struct is not intended to be used directly! + */ struct W3 { int sock; int port; @@ -88,30 +92,73 @@ int W3_Library_Init(void); * @param hostname Hostname * @param port Port * @return - * - `struct W3*` if successful. + * - non-`NULL` if successful. * - `NULL` if not. */ struct W3* W3_Create(const char* protocol, const char* hostname, int port); /** * @brief Sets the method, or the command name. - * @param w3 Pointer to the struct. - * @param method Method, or command name. + * @param w3 Pointer to the struct + * @param method Method, or command name */ void W3_Set_Method(struct W3* w3, const char* method); /** * @brief Sets the path, or the argument. - * @param w3 Pointer to the struct. - * @param path Path, or argument. + * @param w3 Pointer to the struct + * @param path Path, or argument */ void W3_Set_Path(struct W3* w3, const char* path); + +/** + * @brief Sends the request, or just handshake. + * @param w3 Pointer to the struct + */ void W3_Send_Request(struct W3* w3); + +/** + * @brief Sets the header. + * @param w3 Pointer to the struct + * @param key Header key + * @param value Header value + */ void W3_Set_Header(struct W3* w3, const char* key, const char* value); + +/** + * @brief Frees the struct. + * @param w3 Pointer to the struct + */ void W3_Free(struct W3* w3); + +/** + * @brief Sets the event handler. + * @param w3 Pointer to the struct + * @param eventname Event name + * @param func Function pointer + */ void W3_On(struct W3* w3, const char* eventname, void* func); + +/** + * @brief Force-disconnects from the server. + * @param w3 Pointer to the struct + */ void W3_Disconnect(struct W3* w3); + +/** + * @brief Sets the data to be sent. + * @param w3 Pointer to the struct + * @param data Data + * @param size Size of the data + */ void W3_Set_Data(struct W3* w3, char* data, size_t size); + +/** + * @brief Sets the read buffer size. + * @param w3 Pointer to the struct + * @param size Size of the read buffer + * @note This method must be called before the W3_Send_Request. + */ void W3_Set_Read_Size(struct W3* w3, size_t size); #ifdef __cplusplus diff --git a/Library/W3FTP.h b/Library/W3FTP.h index 4ff430c..a88548a 100644 --- a/Library/W3FTP.h +++ b/Library/W3FTP.h @@ -33,6 +33,11 @@ #ifndef __W3FTP_H__ #define __W3FTP_H__ +/** + * @file W3FTP.h + * @brief FTP part of LibW3 + */ + #ifdef __cplusplus extern "C" { #endif @@ -40,9 +45,33 @@ extern "C" { #include "W3Core.h" void __W3_FTP_Request(struct W3* w3); + +/** + * @brief Sets the username of the FTP connection. + * @param w3 Pointer to the struct + * @param username FTP username + */ void W3_FTP_Set_Username(struct W3* w3, const char* username); + +/** + * @brief Sets the password of the FTP connection. + * @param w3 Pointer to the struct + * @param password FTP password + */ void W3_FTP_Set_Password(struct W3* w3, const char* password); + +/** + * @brief Sends the FTP command. + * @param w3 Pointer to the struct + * @note This function is different with W3_Send_Request! + * @note When W3_Send_Request just handshakes, this function sends the FTP command! + */ void W3_FTP_Send_Request(struct W3* w3); + +/** + * @brief Disconnects from the FTP. + * @param w3 Pointer to the struct + */ void W3_FTP_Disconnect(struct W3* w3); #ifdef __cplusplus diff --git a/Library/W3HTTP.h b/Library/W3HTTP.h index 5a37ced..ba02c94 100644 --- a/Library/W3HTTP.h +++ b/Library/W3HTTP.h @@ -33,6 +33,11 @@ #ifndef __W3HTTP_H__ #define __W3HTTP_H__ +/** + * @file W3HTTP.h + * @brief HTTP part of LibW3 + */ + #ifdef __cplusplus extern "C" { #endif @@ -40,6 +45,11 @@ extern "C" { #include "W3Core.h" void __W3_HTTP_Request(struct W3* w3); + +/** + * @brief Enables the redirect. + * @param w3 Pointer to the struct + */ void W3_HTTP_Enable_Redirect(struct W3* w3); #ifdef __cplusplus diff --git a/Library/W3IRC.h b/Library/W3IRC.h index 46f31ed..f38a5d1 100644 --- a/Library/W3IRC.h +++ b/Library/W3IRC.h @@ -33,6 +33,11 @@ #ifndef __W3IRC_H__ #define __W3IRC_H__ +/** + * @file W3IRC.h + * @brief IRC part of LibW3 + */ + #ifdef __cplusplus extern "C" { #endif @@ -40,13 +45,61 @@ extern "C" { #include "W3Core.h" void __W3_IRC_Request(struct W3* w3); + +/** + * @brief Sets the username of the IRC connection. + * @param w3 Pointer to the struct + * @param username IRC username + */ void W3_IRC_Set_Username(struct W3* w3, const char* username); + +/** + * @brief Sets the hostname of the IRC connection. + * @param w3 Pointer to the struct + * @param hostname IRC hostname + */ void W3_IRC_Set_Hostname(struct W3* w3, const char* hostname); + +/** + * @brief Sets the realname of the IRC connection. + * @param w3 Pointer to the struct + * @param realname IRC realname + */ void W3_IRC_Set_Realname(struct W3* w3, const char* realname); + +/** + * @brief Sets the servername of the IRC connection. + * @param w3 Pointer to the struct + * @param servername IRC servername + */ void W3_IRC_Set_Servername(struct W3* w3, const char* servername); + +/** + * @brief Sets the nickname of the IRC connection. + * @param w3 Pointer to the struct + * @param nickname IRC nickname + */ void W3_IRC_Set_Nickname(struct W3* w3, const char* nickname); + +/** + * @brief Sets the password of the IRC connection. + * @param w3 Pointer to the struct + * @param password IRC password + */ void W3_IRC_Set_Password(struct W3* w3, const char* password); + +/** + * @brief Sends the IRC command. + * @param w3 Pointer to the struct + * @note This function is different with W3_Send_Request! + * @note When W3_Send_Request just handshakes, this function sends the IRC command! + */ void W3_IRC_Send_Request(struct W3* w3); + +/** + * @brief Disconnects from the IRC. + * @param w3 Pointer to the struct + */ void W3_IRC_Disconnect(struct W3* w3); #ifdef __cplusplus diff --git a/Library/W3NNTP.h b/Library/W3NNTP.h index ff833e7..67892dc 100644 --- a/Library/W3NNTP.h +++ b/Library/W3NNTP.h @@ -33,6 +33,11 @@ #ifndef __W3NNTP_H__ #define __W3NNTP_H__ +/** + * @file W3NNTP.h + * @brief NNTP part of LibW3 + */ + #ifdef __cplusplus extern "C" { #endif @@ -40,7 +45,19 @@ extern "C" { #include "W3Core.h" void __W3_NNTP_Request(struct W3* w3); + +/** + * @brief Sends the NNTP command. + * @param w3 Pointer to the struct + * @note This function is different with W3_Send_Request! + * @note When W3_Send_Request just handshakes, this function sends the NNTP command! + */ void W3_NNTP_Send_Request(struct W3* w3); + +/** + * @brief Disconnects from the NNTP. + * @param w3 Pointer to the struct + */ void W3_NNTP_Disconnect(struct W3* w3); #ifdef __cplusplus diff --git a/Library/W3POP3.h b/Library/W3POP3.h index 3a14773..519b353 100644 --- a/Library/W3POP3.h +++ b/Library/W3POP3.h @@ -33,6 +33,12 @@ #ifndef __W3POP3_H__ #define __W3POP3_H__ +/** + * @file W3POP3.h + * @brief POP3 part of LibW3 + * @deprecated Nishi might abandon this + */ + #ifdef __cplusplus extern "C" { #endif @@ -40,9 +46,33 @@ extern "C" { #include "W3Core.h" void __W3_POP3_Request(struct W3* w3); + +/** + * @brief Sets the username of the POP3 connection. + * @param w3 Pointer to the struct + * @param username POP3 username + */ void W3_POP3_Set_Username(struct W3* w3, const char* username); + +/** + * @brief Sets the username of the POP3 connection. + * @param w3 Pointer to the struct + * @param username POP3 username + */ void W3_POP3_Set_Password(struct W3* w3, const char* password); + +/** + * @brief Sends the POP3 command. + * @param w3 Pointer to the struct + * @note This function is different with W3_Send_Request! + * @note When W3_Send_Request just handshakes, this function sends the POP3 command! + */ void W3_POP3_Send_Request(struct W3* w3); + +/** + * @brief Disconnects from the POP3. + * @param w3 Pointer to the struct + */ void W3_POP3_Disconnect(struct W3* w3); #ifdef __cplusplus diff --git a/Library/W3Tag.h b/Library/W3Tag.h index eb3d8dd..78db173 100644 --- a/Library/W3Tag.h +++ b/Library/W3Tag.h @@ -33,13 +33,37 @@ #ifndef __W3TAG_H__ #define __W3TAG_H__ +/** + * @file W3Tag.h + * @brief Tag parser + */ + #ifdef __cplusplus extern "C" { #endif #include +/** + * @brief Parses the data. + * @param data Data to be parsed + * @param size Size of the data + * @param tagfunc Function to be called when the parser hits a tag + * @param tagfunc.tagname Tag name + * @param tagfunc.attr Tag attributes + * @param textfunc Function to be called when the parser hits a text + * @param textfunc.data Text + */ void W3_Tag_Parse(char* data, size_t size, void (*tagfunc)(char* tagname, char* attr), void (*textfunc)(char* data)); + +/** + * @brief Gets the attribute. + * @param data Data to be parsed + * @param name Attribute name + * @return + * - non-`NULL` if it could find the attribute + * - `NULL` if it couldn't + */ char* W3_Tag_Attr(char* data, const char* name); #ifdef __cplusplus diff --git a/Library/W3Tcl.h b/Library/W3Tcl.h index d6ea39c..9ac65a2 100644 --- a/Library/W3Tcl.h +++ b/Library/W3Tcl.h @@ -33,12 +33,22 @@ #ifndef __W3URL_H__ #define __W3URL_H__ +/** + * @file W3Tcl.h + * @brief Tcl binding + */ + #ifdef __cplusplus extern "C" { #endif #include +/** + * @brief Initializes LibW3 for Tcl + * @param interp Tcl interpreter + * @return Tcl error code + */ int W3_Init(Tcl_Interp* interp); #ifdef __cplusplus diff --git a/Library/W3URL.h b/Library/W3URL.h index 3fa9216..9c61b3c 100644 --- a/Library/W3URL.h +++ b/Library/W3URL.h @@ -33,20 +33,65 @@ #ifndef __W3URL_H__ #define __W3URL_H__ +/** + * @file W3URL.h + * @brief URL parser + */ + #ifdef __cplusplus extern "C" { #endif +/** + * @brief URL struct + */ struct W3URL { + /** + * @brief Protocol + */ char* protocol; + + /** + * @brief Host + */ char* host; + + /** + * @brief Port + */ int port; + + /** + * @brief Path + */ char* path; + + /** + * @brief Username + * @note `NULL` if the parser could not find the username. + */ char* username; + + /** + * @brief Password + * @note `NULL` if the parser could not find the password. + */ char* password; }; +/** + * @brief Parses the URL. + * @param url URL + * @return + * - non-`NULL` if successful. + * - `NULL` if not. + */ struct W3URL* W3_Parse_URL(const char* url); + +/** + * @brief Frees the struct. + * @param url Pointer to the struct + */ void W3_Free_URL(struct W3URL* url); #ifdef __cplusplus diff --git a/Library/W3Util.h b/Library/W3Util.h index a1ab3f6..b601926 100644 --- a/Library/W3Util.h +++ b/Library/W3Util.h @@ -33,6 +33,11 @@ #ifndef __W3UTIL_H__ #define __W3UTIL_H__ +/** + * @file W3Util.h + * @brief LibW3 utilities + */ + #ifdef __cplusplus extern "C" { #endif @@ -41,6 +46,10 @@ extern "C" { #include +/** + * @brief Turn on/off debugging. + * @param do_debug Do debugging or not + */ void W3_Do_Debug(bool do_debug); void __W3_Debug(const char* title, const char* message); char* __W3_Concat(const char* str1, const char* str2); -- 2.43.0