document generating

git-svn-id: file:///raid/svn-main/nishi-libw3/trunk@271 d27a3e52-49c5-7645-884c-6793ebffc270

diff --git a/Doxyfile b/Doxyfile
index 9343f564a09a26ebdbcdf55204aebdf19d1b8af6..4eef145ff168e6fac603cf2eae94664fcbaee9c3 100644 (file)
--- 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 b7539a06a03bf57c6cf66d3771367e7e4d2ff7b4..14e6b38d2545302042c759b0e2fc3b5e39ff3d5c 100644 (file)
--- 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 4ff430c3a2d343548d126a163084414e84b9eed4..a88548aa817faad1361dabfa07333b3da93c2bb2 100644 (file)
--- 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 5a37ced705f6cbd08922a3be9b606048cfba551c..ba02c94e0d0bbf38c0ba52b21b7bc358cee8f1f2 100644 (file)
--- 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 46f31ed5da5aedf0e61b1d8d6daaa36c0d2accfc..f38a5d16a706d8d132133e6c9a77fbff3b2a4207 100644 (file)
--- 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 ff833e75279d4899480b1933b674076e95be7969..67892dc42d8cd20b35f7187bad07c457c3fe218b 100644 (file)
--- 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 3a1477372e3a6e948b2ce92e58a18a856fa3b60b..519b353748c47346d8f0b7cdba9360f0ce071e15 100644 (file)
--- 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 eb3d8dd0ed3dd0a2cb12ce8fb817b089032a8b0c..78db173bf63ae49ccbebbe33f906ffe23806cb35 100644 (file)
--- 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 <stddef.h>
 
+/**
+ * @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 d6ea39c66cc105c2930639d799c32bbb0e1f5244..9ac65a231d13c95114099e38b31a23cccd3055ab 100644 (file)
--- 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 <tcl.h>
 
+/**
+ * @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 3fa9216fb56343b5e00fb8b25cbe433273c2fb32..9c61b3c03cdcf3301bafe84c3128baec2b4c7a8a 100644 (file)
--- 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 a1ab3f610f7bb4c21c58a4d2e8741ec7ab47619b..b60192601faa17160f1e3db96325d7606fed0f46 100644 (file)
--- 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 <stdbool.h>
 
+/**
+ * @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);