[Xcb] doxygen doc of the API

[Vincent Torri]

Hey,

Here is the modified file. I have added the const for the returned value
of XCBGetSetup.

> Note that XCBGenericRep is a generic reply, not a generic response. The
> term "response" is used to refer to any reply, error, or event.

i've fixed that

>
> Were you planning on including documentation on internal APIs here? If
> not, it's kind of weird that the file list has xcbint.h and all the
> source files. It should arguably cover only xcb.h, xcbext.h, and
> xcbxlib.h. Possibly it should also cover xproto.h and others, but only
> if you can auto-generate part or all of that documentation from the
> original XML.

No, i didn't want that. It's only doxygen that have added it. It's just
something to tweak in the configuration file that generate the doc. Not a
big stuff.

> >  i also would like to add some presentation on the main page. For example:
> >
> >  * general presentation (from the wiki)
> >  * a small example of code
> >  * something else ?
>
> I think your tutorial is the place for code samples, etc. A link to your
> tutorial wouldn't be a bad thing for the main page of the API
> documentaiton though.

ok

> >  we can add some todo items, if some functions need to.
>
> I'm not sure I understand this. You mean if the functions have planned
> interface changes? At this point, if I could remember that I planned to
> change the interface, I've done it already.

with doxygen, we can add "todo" items, that is, we can add a @todo
paragraph somewhere, and doxygen adds a page with all the todo.
But, nevermind, i've added  the 2 todo in bugzilla :) I've let them in
xcb.h.diff, though.

Now, we should choose between 2 solutions for the documentation:

1) we add
documentation in each module (xcb(code), xcb-proto, xcb-utils)  and
generate the doc in each of them.

2) we add the doc in each module, and we place all the doc in one place
(and we define groups, like i've done in xcb.h, see the beginning of the
file)

what do you think ?

Vincent
-------------- next part --------------
--- xcb.h	2006-03-03 21:40:46.000000000 +0100
+++ xcb_doc.h	2006-03-04 08:25:35.203552240 +0100
@@ -42,15 +42,27 @@
 #define deprecated
 #endif
 
+
+/**
+ * @file xcb.h
+ */
+
+/**
+ * @defgroup XCB_Core_Api XCB Core API
+ * @brief Core API of the XCB library.
+ *
+ * @{
+ */
+
 /* Pre-defined constants */
 
-/* current protocol version */
+/** Current protocol version */
 #define X_PROTOCOL 11
 
-/* current minor version */
+/** Current minor version */
 #define X_PROTOCOL_REVISION 0
 
-/* X_TCP_PORT + display number = server port for TCP transport */
+/** X_TCP_PORT + display number = server port for TCP transport */
 #define X_TCP_PORT 6000
 
 #define XCB_TYPE_PAD(T,I) (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1))
@@ -58,42 +70,72 @@
 
 /* Opaque structures */
 
-typedef struct XCBConnection XCBConnection;
+/**
+ * @brief XCB Connection structure.
+ *
+ * A structure that contain all data that  XCB needs to communicate with an X server.
+ */
+typedef struct XCBConnection XCBConnection;  /**< Opaque structure containing all data that  XCB needs to communicate with an X server. */
 
 
 /* Other types */
 
+/**
+ * @brief Generic iterator.
+ *
+ * A generic iterator structure.
+ */
 typedef struct {
-    void *data;
-    int rem;
-    int index;
+    void *data;   /**< Data of the current iterator */
+    int rem;    /**< remaining elements */
+    int index;  /**< index of the current iterator */
 } XCBGenericIter;
 
+/**
+ * @brief Generic reply.
+ *
+ * A generic reply structure.
+ */
 typedef struct {
-    BYTE response_type;
-    CARD8 pad0;
-    CARD16 sequence;
-    CARD32 length;
+    BYTE   response_type;  /**< Type of the response */
+    CARD8  pad0;           /**< Padding */
+    CARD16 sequence;       /**< Sequence number */
+    CARD32 length;         /**< Length of the response */
 } XCBGenericRep;
 
+/**
+ * @brief Generic event.
+ *
+ * A generic event structure.
+ */
 typedef struct {
-    BYTE response_type;
-    CARD8 pad0;
-    CARD16 sequence;
-    CARD32 pad[7];
+    BYTE   response_type;  /**< Type of the response */
+    CARD8  pad0;           /**< Padding */
+    CARD16 sequence;       /**< Sequence number */
+    CARD32 pad[7];         /**< Padding */
     CARD32 full_sequence;
 } XCBGenericEvent;
 
+/**
+ * @brief Generic error.
+ *
+ * A generic error structure.
+ */
 typedef struct {
-    BYTE response_type;
-    BYTE error_code;
-    CARD16 sequence;
-    CARD32 pad[7];
+    BYTE   response_type;  /**< Type of the response */
+    BYTE   error_code;     /**< Error code */
+    CARD16 sequence;       /**< Sequence number */
+    CARD32 pad[7];         /**< Padding */
     CARD32 full_sequence;
 } XCBGenericError;
 
+/**
+ * @brief Generic cookie.
+ *
+ * A generic cookie structure.
+ */
 typedef struct {
-    unsigned int sequence;
+    unsigned int sequence;  /**< Sequence number */
 } XCBVoidCookie;
 
 
@@ -104,64 +146,322 @@
 
 /* xcb_auth.c */
 
+/**
+ * @brief Container for authorization information.
+ *
+ * A container for authorization information to be sent to the X server.
+ */
 typedef struct XCBAuthInfo {
-    int namelen;
-    char *name;
-    int datalen;
-    char *data;
+    int   namelen;  /**< Length of the string name (as returned by strlen). */
+    char *name;     /**< String containing the authentication protocol name, such as "MIT-MAGIC-COOKIE-1" or "XDM-AUTHORIZATION-1". */
+    int   datalen;  /**< Length of the data member. */
+    char *data;   /**< Data interpreted in a protocol-specific manner. */
 } XCBAuthInfo;
 
+/**
+ * @brief Gets authorization information.
+ * @param fd: The file descriptor.
+ * @param info: The authorisation info to set.
+ * @return @c 0 on failure, 1 otherwise.
+ *
+ * @deprecated This function is deprecated. It must not be used in
+ * newly written code.
+ */
 int XCBGetAuthInfo(int fd, XCBAuthInfo *info) deprecated;
 
 
 /* xcb_out.c */
 
+/**
+ * @brief Forces any buffered output to be written to the server.
+ * @param c: The connection to the X server.
+ * @return > @c 0 on success, <= @c 0 otherwise.
+ *
+ * Forces any buffered output to be written to the server. Blocks
+ * until the write is complete.
+ *
+ * @todo Change the value of the return (0 on failure, 1 on success).
+ */
 int XCBFlush(XCBConnection *c);
+
+/**
+ * @brief Returns the maximum request length field from the connection
+ * setup data.
+ * @param c: The connection to the X server.
+ * @return The maximum request length field.
+ *
+ * In the absence of the BIG-REQUESTS extension, returns the
+ * maximum request length field from the connection setup data, which
+ * may be as much as 65535. If the server supports BIG-REQUESTS, then
+ * the maximum request length field from the reply to the
+ * BigRequestsEnable request will be returned instead.
+ *
+ * Note that this length is measured in four-byte units, making the
+ * theoretical maximum lengths roughly 256kB without BIG-REQUESTS and
+ * 16GB with.
+ */
 CARD32 XCBGetMaximumRequestLength(XCBConnection *c);
 
 
 /* xcb_in.c */
 
+/**
+ * @brief Returns the next event or error from the server.
+ * @param c: The connection to the X server.
+ * @return The next event from the server.
+ *
+ * @deprecated This function is deprecated. It must not be used in
+ * newly written code.
+ */
 XCBGenericEvent *XCBWaitEvent(XCBConnection *c) deprecated;
+
+/**
+ * @brief Returns the next event or error from the server.
+ * @param c: The connection to the X server.
+ * @return The next event from the server.
+ *
+ * Returns the next event or error from the server, or returns null in
+ * the event of an I/O error. Blocks until either an event or error
+ * arrive, or an I/O error occurs.
+ */
 XCBGenericEvent *XCBWaitForEvent(XCBConnection *c);
+
+/**
+ * @brief Returns the next event or error from the server.
+ * @param c: The connection to the X server.
+ * @param error: A pointer to an int to be filled in with the I/O
+ * error status of the operation.
+ * @return The next event from the server.
+ *
+ * Returns the next event or error from the server, if one is
+ * available, or returns @c NULL otherwise. If no event is available, that
+ * might be because an I/O error like connection close occurred while
+ * attempting to read the next event. The @p error parameter is a
+ * pointer to an int to be filled in with the I/O error status of the
+ * operation. If @p error is @c NULL, terminates the application when an
+ * I/O error occurs.
+ */
 XCBGenericEvent *XCBPollForEvent(XCBConnection *c, int *error);
+
+/**
+ * @brief Returns the last sequence number that the server is known to
+ * have processed.
+ * @param c: The connection to the X server.
+ * @return The last sequence number.
+ *
+ * Returns the last sequence number that the server is known to have
+ * processed. This function enables applications to determine whether
+ * forcing a cookie is going to block.
+ *
+ * @todo review that function.
+ */
 unsigned int XCBGetRequestRead(XCBConnection *c);
 
 
 /* xcb_ext.c */
 
-typedef struct XCBExtension XCBExtension;
-
-/* Do not free the returned XCBQueryExtensionRep - on return, it's aliased
- * from the cache. */
+/**
+ * @typedef typedef struct XCBExtension XCBExtension
+ */
+typedef struct XCBExtension XCBExtension;  /**< Opaque structure used as key for XCBGetExtensionData. */
+
+/**
+ * @brief Caches reply information from QueryExtension requests.
+ * @param c: The connection.
+ * @param ext: The extension data.
+ * @return A pointer to a XCBConnSetupSuccessRep pointer.
+ *
+ * This function is the primary interface to the "extension cache",
+ * which caches reply information from QueryExtension
+ * requests. Invoking this function may cause a call to
+ * XCBQueryExtension to retrieve extension information from the
+ * server, and may block until extension data is received from the
+ * server.
+ *
+ * The result must not be freed. This storage is managed by the cache
+ * itself.
+ */
 const XCBQueryExtensionRep *XCBGetExtensionData(XCBConnection *c, XCBExtension *ext);
 
+/**
+ * @brief Prefetch of extension data into the extension cache
+ * @param c: The connection.
+ * @param ext: The extension data.
+ *
+ * This function allows a "prefetch" of extension data into the
+ * extension cache. Invoking the function may cause a call to
+ * XCBQueryExtension, but will not block waiting for the
+ * reply. XCBGetExtensionData will return the prefetched data after
+ * possibly blocking while it is retrieved.
+ */
 void XCBPrefetchExtensionData(XCBConnection *c, XCBExtension *ext);
 
 
 /* xcb_conn.c */
 
-XCBConnSetupSuccessRep *XCBGetSetup(XCBConnection *c);
+/**
+ * @brief Access the data returned by the server.
+ * @param c: The connection.
+ * @return A pointer to a XCBConnSetupSuccessRep pointer.
+ *
+ * Accessor for the data returned by the server when the XCBConnection
+ * was initialized. This data includes
+ * - the server's required format for images,
+ * - a list of available visuals,
+ * - a list of available screens,
+ * - the server's maximum request length (in the absence of the
+ * BIG-REQUESTS extension),
+ * - and other assorted information.
+ *
+ * See the X protocol specification for more details.
+ *
+ * The result must not be freed.
+ */
+const XCBConnSetupSuccessRep *XCBGetSetup(XCBConnection *c);
+
+/**
+ * @brief Access the file descriptor of the connection.
+ * @param c: The connection.
+ * @return The file descriptor.
+ *
+ * Accessor for the file descriptor that was passed to the
+ * XCBConnectToFD call that returned @p c.
+ */
 int XCBGetFileDescriptor(XCBConnection *c);
 
+/**
+ * @brief Connects to the X server.
+ * @param fd: The file descriptor.
+ * @param auth_info: Authentication data.
+ * @return A newly allocated XCBConnection structure.
+ *
+ * Connects to an X server, given the open socket @p fd and the
+ * XCBAuthInfo @p auth_info. The file descriptor @p fd is
+ * bidirectionally connected to an X server. XCBGetTCPFD and
+ * XCBGetUnixFD return appropriate file descriptors. If the connection
+ * should be unauthenticated, @p auth_info must be @c
+ * NULL. XCBGetAuthInfo returns appropriate authentication data.
+ */
 XCBConnection *XCBConnectToFD(int fd, XCBAuthInfo *auth_info);
+
+/**
+ * @brief Closes the connection.
+ * @param c: The connection.
+ *
+ * Closes the file descriptor and frees all memory associated with the
+ * connection @c c.
+ */
 void XCBDisconnect(XCBConnection *c);
 
 
 /* xcb_util.c */
 
+/**
+ * @brief Parses a display string name in the form documented by X(7x).
+ * @param displayname: The name of the display.
+ * @param hostp: A pointer to a malloc'd copy of the hostname.
+ * @param displayp: A pointer to the display number.
+ * @param screenp: A pointer to the screen number.
+ * @return 0 on failure, non 0 otherwise.
+ *
+ * Parses the display string name @p display_name in the form
+ * documented by X(7x). Has no side effects on failure. If
+ * @p displayname is @c NULL or empty, it uses the environment
+ * variable DISPLAY. @p hostp is a pointer to a newly allocated string
+ * that contain the host name. @p displayp is set to the display
+ * number and @p screenp to the preferred screen number. @p screenp
+ * can be @c NULL. If @p displayname does not contain a screen number,
+ * it is set to @c 0.
+ */
 int XCBParseDisplay(const char *name, char **host, int *display, int *screen);
+
+/**
+ * @brief Open a connection to the X server.
+ * @param host: The host name.
+ * @param display: The display number.
+ * @return The file descriptor.
+ *
+ * @deprecated This function is deprecated. It must not be used in
+ * newly written code.
+ */
 int XCBOpen(const char *host, int display) deprecated;
+
+/**
+ * @brief Open a connection to the X server.
+ * @param host: The host name.
+ * @param port: The TCP port.
+ * @return The file descriptor.
+ *
+ * @deprecated This function is deprecated. It must not be used in
+ * newly written code.
+ */
 int XCBOpenTCP(const char *host, unsigned short port) deprecated;
+
+/**
+ * @brief Connects to the X server.
+ * @param file: The file name.
+ * @return The file descriptor.
+ *
+ * @deprecated This function is deprecated. It must not be used in
+ * newly written code.
+ */
 int XCBOpenUnix(const char *file) deprecated;
 
+/**
+ * @brief Connects to the X server.
+ * @return A newly allocated XCBConnection structure.
+ *
+ * @deprecated This function is deprecated. It must not be used in
+ * newly written code.
+ */
 XCBConnection *XCBConnectBasic(void) deprecated;
+
+/**
+ * @brief Connects to the X server.
+ * @param displayname: The name of the display.
+ * @param screenp: A pointer to a preferred screen number.
+ * @return A newly allocated XCBConnection structure.
+ *
+ * Connects to the X server specified by @p displayname. If @p
+ * displayname is @c NULL, uses the value of the DISPLAY environment
+ * variable. If a particular screen on that server is preferred, the
+ * int pointed to by @p screenp (if not @c NULL) will be set to that
+ * screen; otherwise the screen will be set to 0.
+ */
 XCBConnection *XCBConnect(const char *displayname, int *screenp);
+
+/**
+ * @brief Connects to the X server, using an authorization information.
+ * @param displayname: The name of the display.
+ * @param auth: The authorization information.
+ * @param screenp: A pointer to a preferred screen number.
+ * @return A newly allocated XCBConnection structure.
+ *
+ * Connects to the X server specified by @p displayname, using the
+ * authorization @p auth. If a particular screen on that server is
+ * preferred, the int pointed to by @p screenp (if not @c NULL) will
+ * be set to that screen; otherwise @p screenp will be set to 0.
+ */
 XCBConnection *XCBConnectToDisplayWithAuthInfo(const char *display, XCBAuthInfo *auth, int *screen);
 
+/**
+ * @brief Ensures that all events and errors are avalaible in XCB.
+ * @param c: The connection to the X server.
+ * @param e: A pointer to an error.
+ * @return @c 1 on success, @c 0 otherwise.
+ *
+ * Blocks the calling thread for the duration of one round trip to the
+ * server, ensuring that all events and errors caused by previous
+ * requests are available to XCB.
+ */
 int XCBSync(XCBConnection *c, XCBGenericError **e);
 
 
+/**
+ * @}
+ */
+
+
 #ifdef __cplusplus
 }
 #endif