[Xcb] api documentation with doxygen
Vincent Torri
Vincent.Torri at iecn.u-nancy.fr
Wed Jun 15 03:49:29 PDT 2005
On Wed, 15 Jun 2005, Jamey Sharp wrote:
> On Sat, 2005-05-21 at 09:33 +0200, Vincent Torri wrote:
> > Hello,
>
> Hi Vincent!
>
> > i've just made a first attempt of api documentation in xcb-util with
> > doxygen. I have documented only 2 functions. You can see the result here:
> >
> > http://www.iecn.u-nancy.fr/~torri/files/xcb/doc/html/
> >
> > do you think it is worth continuing documenting xcb-util ?
> >
> > I have also xslt files that could give you gtk documentation style, if you
> > don't like doxygen output (like me ;) )
>
> Documentation is a good thing, definitely. I'm glad somebody is thinking
> about it. :-)
>
> I don't have any particular preference for which tools or styles to use
> in the documentation, so I think it's pretty much up to whoever
> implements it. Which means I think you get to make it look however you
> want, Vincent. :-)
>
> I'd like to see what the changes to the code look like before we start
> adding documentation all over the place, though. It looks to me like you
> haven't committed your changes for the XCBImage documentation: would you
> post a patch to the mailing list so we can see what this stuff looks
> like?
About the tool, doxygen is the mst used and the most advanced. About the
style, I use the xml output of doxygen, and I create a html file from it
with a stylesheet file.
About the code, I prefer putting the documentation in the headers:
usually, when I look at an api, i look at the header. If in addition,
there is a documentation inside, it's better :) In addition, in the
header, there are all the api functions. So, if we document the header, we
should be abl to comment all the functions without ommiting one, and also
only which are necessary for the user
Anyway, some documentation in the header is needed as we could document
the enums, structs, macros, etc...
Vincent
-------------- next part --------------
--- xcb_image_cvs.h 2005-06-15 11:38:21.690471591 +0200
+++ xcb_image.h 2005-05-22 17:37:09.000000000 +0200
@@ -3,7 +3,14 @@
#define __XCB_IMAGE_H__
-typedef struct XCBImage_ XCBImage;
+/**
+ * @defgroup XCB_Image XCB Image Functions
+ *
+ * Functions used to create and manipulate images.
+ */
+
+
+typedef struct XCBImage_ XCBImage; /**< A structure that describes an XCBImage */
struct XCBImage_
{
@@ -30,6 +37,34 @@
BYTE *shmaddr;
};
+/**
+ * Create a new Image.
+ * @param conn The connection to the X server.
+ * @param depth The depth of the image.
+ * @param format The format of the image. You can pass XYBitmap,
+ * XYPixmap, or ZPixmap.
+ * @param offset The number of pixels to ignore at the beginning of
+ * the scanline.
+ * @param data The image data.
+ * @param width The width of the image, in pixels.
+ * @param height The height of the image, in pixels.
+ * @param xpad The quantum of a scanline (8, 16, or 32).
+ * @param bytes_per_line The number of bytes in the client image
+ * between the start of one scanline and the start of the next.
+ * @return The new image.
+ *
+ * This function allocates the memory needed for an XCBImage structure
+ * for the specified connection but does not allocate space for the image
+ * itself. It initializes the structure byte-order, bit-order, and
+ * bitmap-unit values from the connection and returns a pointer to the
+ * XCBImage structure.
+ *
+ * The @p offset parameter permits the rapid displaying of the image
+ * without requiring each scanline to be shifted into position.
+ *
+ * The image must be destroyed with @ref XCBImageDestroy.
+ * @ingroup XCB_Image
+ */
XCBImage *XCBImageCreate (XCBConnection *conn,
CARD8 depth,
CARD8 format,
@@ -40,10 +75,50 @@
CARD8 xpad,
CARD32 bytes_per_line);
+/**
+ * Initialize an Image.
+ * @param image The image to be destroyed.
+ * @return 1 if the operation has succeeded.
+ *
+ * This function initializes the image structure.
+ * @ingroup XCB_Image
+ */
int XCBImageInit (XCBImage *image);
+/**
+ * Destroy an Image.
+ * @param image The image to be destroyed.
+ * @return 1 if the operation has succeeded.
+ *
+ * This function deallocates both the memory associated with the @p image
+ * parameter and its data.
+ * @ingroup XCB_Image
+ */
int XCBImageDestroy (XCBImage *image);
+/**
+ * Return a pointer to a XCBImage.
+ * @param conn The connection to the X server.
+ * @param draw The draw you get the image from.
+ * @param x The x coordinate, which are relative to the origin of the
+ * drawable and define the upper-left corner of the rectangle.
+ * @param y The y coordinate, which are relative to the origin of the
+ * drawable and define the upper-left corner of the rectangle.
+ * @param width The width of the subimage, in pixels.
+ * @param height The height of the subimage, in pixels.
+ * @param plane_mask The plane mask.
+ * @param format The format of the image. You can pass XYBitmap,
+ * XYPixmap, or ZPixmap.
+ * @return The subimage of @p draw defined by @p x, @p y, @p w, @p h.
+ *
+ * This function returns a subimage of @p draw defined by @p x, @p y,
+ * @p w, @p h. The depth of the image is the one of the drawable @p
+ * draw, except when getting a subset of the plane in @c XYPixmap
+ * format.
+ *
+ * If a problem occurs, the functons returns @c NULL.
+ * @ingroup XCB_Image
+ */
XCBImage *XCBImageGet (XCBConnection *conn,
XCBDRAWABLE draw,
INT16 x,
@@ -66,6 +141,37 @@
int dest_x,
int dest_y);
+/**
+ * Return a pointer to a XCBImage.
+ * @param conn The connection to the X server.
+ * @param draw The draw you get the image from.
+ * @param gc The graphic context.
+ * @param image The image you want to combine with the rectangle.
+ * @param x_offset The offset in x from the left edge of the image
+ * defined by the XCBImage structure.
+ * @param y_offset The offset in y from the left edge of the image
+ * defined by the XCBImage structure.
+ * @param x The x coordinate, which is relative to the origin of the
+ * drawable and defines the x coordinate of the upper-left corner of the
+ * rectangle.
+ * @param y The y coordinate, which is relative to the origin of the
+ * drawable and defines the x coordinate of the upper-left corner of
+ * the rectangle.
+ * @param width The width of the subimage, in pixels.
+ * @param height The height of the subimage, in pixels.
+ * @return 1 is no problems occurs.
+ *
+ * This function combines an image with a rectangle of the specified
+ * drawable. The section of the image defined by the @p x, @p y,
+ * @p width, and @p height arguments is drawn on the specified part of
+ * the drawable. The foreground pixel in @p gc defines the source for
+ * the one bits in the image, and the background pixel defines the
+ * source for the zero bits. For XYPixmap and ZPixmap formats, the
+ * depth of the image must match the depth of the drawable.
+ *
+ * If a problem occurs, the functons returns @c NULL.
+ * @ingroup XCB_Image
+ */
int XCBImagePut (XCBConnection *conn,
XCBDRAWABLE draw,
XCBGCONTEXT gc,
@@ -77,11 +183,39 @@
CARD16 width,
CARD16 height);
+/**
+ * Put a pixel in a image
+ * @param image The image.
+ * @param x The x coordinate of the pixel.
+ * @param y The y coordinate of the pixel.
+ * @param pixel The new pixel value.
+ * @return 1 if the operation has succeeded.
+ *
+ * This function overwrites the pixel in the named image with the
+ * specified @p pixel value. The input pixel value must be in normalized
+ * format (that is, the least-significant byte of the long is the
+ * least-significant byte of the pixel). The image must contain the @p x
+ * and @p y coordinates.
+ * @ingroup XCB_Image
+ */
int XCBImagePutPixel (XCBImage *image,
int x,
int y,
CARD32 pixel);
+/**
+ * Get a pixel in a image
+ * @param image The image.
+ * @param x The x coordinate of the pixel.
+ * @param y The y coordinate of the pixel.
+ * @return The pixel value.
+ *
+ * This function returns the specified pixel from the named image. The
+ * pixel value is returned in normalized format (that is, the
+ * least-significant byte of the long is the least-significant byte of
+ * the pixel). The image must contain the @p x and @p y coordinates.
+ * @ingroup XCB_Image
+ */
CARD32 XCBImageGetPixel (XCBImage *image,
int x,
int y);
More information about the xcb
mailing list