[Xcb] doxygen and documentation
Vincent Torri
vtorri at univ-evry.fr
Thu Oct 19 14:47:52 PDT 2006
Hey,
here is a diff that allows to build the documentation with make (and not
by typing 'doxygen etc...' The corresponding Makefile.am is also attached.
It has to go into doc/
I would prefer to put xcb.doxygen in the doc/ dir, and rename it Doxyfile.
Vincent
On Thu, 19 Oct 2006, Jeremy Kolb wrote:
> Jamey Sharp wrote:
>> On Wed, Oct 18, 2006 at 09:40:08PM -0400, Jeremy Kolb wrote:
>>> So I know nothing of xslt or doxygen but I hacked up this diff to
>>> generate doxygen comments for the proto headers. Most of it is stub
>>> work and shows us where we need to go from here but the resulting html
>>> pages are pretty cool.
>>
>> Great! This is exactly what I wanted for a first step in this direction.
>> Thanks!
>>
>> This finally prompted me to run doxygen and put up the output at
>> http://xcb.freedesktop.org/manual/
>> which should replace our XcbApi pages. If somebody gets around to fixing
>> the wiki before I do I sure won't complain. :-) Checking that everything
>> on the wiki is also in the Doxygen comments is a necessary first step...
>>
>>> My xslt sucks and the patch needs to be cleaned up a lot, it's just a
>>> proof of concept hack.
>>
>> I thought about applying it anyway, but I'd like Josh to review first. I
>> bet he can make it a lot easier to describe these generated comments.
>>
>
> That would be really good. If we could modularize it some how then all
> the better.
>
>> However, I generated the above page using the patched c-client.
>>
>>> 1. We need some type of <brief> or <description> field that we can tie
>>> in to items/fields/requests/constants/etc., to give a basic description
>>> of an item.
>>
>> An old goal that I still hope for here is to be able to take the full
>> text from the original protocol specifications and incorporate it into
>> the XML descriptions. That text then can be copied into the Doxygen
>> comments, as well as being used to regenerate pure protocol
>> documentation. If that has to be split into a "brief" and "full"
>> description, I guess that's OK, but I'm inclined to turn on Doxygen's
>> JAVADOC_AUTOBRIEF mode and get rid of all the explicit "@brief" tags.
>>
>
> JAVADOC_AUTOBRIEF creates the brief for you? I think it's best to have
> both. A brief for things like fields etc. and fully describe them, and
> a full for the giant block of text.
>
>>> 2. Maybe a <throws> or similar tag... something like <throws
>>> name="BadMatch" when="index is out of range" /> so we can document
>>> which requests throw what errors (and events?).
>>
>> I think that'd be great. Even better if we can devise a description that
>> allows some simple test cases or server-side checks to be
>> auto-generated.
>>
> That would be pretty cool. I hadn't thought of that.
>
>>> 3. I think it would be worth while to make enums field types and then
>>> when generating c code replace the field type with uint32_t or whatever.
>>> That would be really good for documentation and higher level bindings.
>>
>> Yes, please. :-) I think it's not even an ABI change, though that's
>> worth checking. Propose a patch?
>
> I'll look into it.
>
>>
>> --Jamey
>>
>>
>> ------------------------------------------------------------------------
>>
>> _______________________________________________
>> Xcb mailing list
>> Xcb at lists.freedesktop.org
>> http://lists.freedesktop.org/mailman/listinfo/xcb
>
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
>
> --
> Ce message a été vérifié par MailScanner
> pour des virus ou des polluriels et rien de
> suspect n'a été trouvé.
> Message délivré par le serveur de messagerie de l'Université d'Evry.
>
>
-------------- next part --------------
if BUILD_DOCS
# install documentation
docdir = $(datadir)/$(PACKAGE)/doc
all-local: doc-build.stamp
# rule to remove all old created files
doc-prepare.stamp:
@if test -d html ; then \
rm -rf html/; \
fi
# rule to build documentation and copy necessary files
doc-build.stamp: doc-prepare.stamp
@cd .. && doxygen xcb.doxygen
# rules to clean
clean-local:
@rm -rf html/
# rule to install the documentation in $(docdir)
install-data-local:
@if ! test -d "$(DESTDIR)$(datadir)/$(PACKAGE)"; then \
$(mkinstalldirs) "$(DESTDIR)$(datadir)/$(PACKAGE)"; \
fi
@if ! test -d "$(DESTDIR)$(docdir)"; then \
$(mkinstalldirs) "$(DESTDIR)$(docdir)"; \
fi
@cp -pr html/ "$(DESTDIR)$(docdir)"
# rule to uninstall the documentation
uninstall-local:
rm -rf $(DESTDIR)$(docdir)
endif
-------------- next part --------------
diff --git a/Makefile.am b/Makefile.am
index b9f7a1f..65edce1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,4 +1,4 @@
-SUBDIRS=src tests
+SUBDIRS=src tests doc
pkgconfigdir = $(libdir)/pkgconfig
@@ -48,4 +48,5 @@ xcb-xfixes.pc.in \
xcb-xprint.pc.in \
xcb-xtest.pc.in \
xcb-xv.pc.in \
-xcb-xvmc.pc.in
+xcb-xvmc.pc.in \
+xcb.doxygen
diff --git a/acinclude.m4 b/acinclude.m4
index 5a6993d..8c9bf63 100644
--- a/acinclude.m4
+++ b/acinclude.m4
@@ -27,3 +27,76 @@ extern void f(int);
AC_MSG_RESULT(no)])
CFLAGS=${save_CFLAGS}
])
+dnl Configure script for doxygen
+dnl Vincent Torri 2005-22-09
+dnl
+dnl AM_CHECK_DOXYGEN([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]])
+dnl Test for the doxygen program, and define BUILD_DOCS and DOXYGEN.
+dnl
+AC_DEFUN([AM_CHECK_DOXYGEN],
+ [
+ DOXYGEN="doxygen"
+ dnl
+ dnl Disable the build of the documentation
+ dnl
+ AC_ARG_ENABLE(
+ [build_docs],
+ AC_HELP_STRING(
+ [--disable-build-docs],
+ [Disable the build of the documentation]),
+ [if test "${disable_build_docs}" = "yes" ; then
+ enable_build_docs="no"
+ else
+ enable_build_docs="yes"
+ fi],
+ [enable_build_docs="yes"])
+ dnl
+ dnl Get the prefix where doxygen is installed.
+ dnl
+ AC_ARG_WITH(
+ [doxygen],
+ AC_HELP_STRING(
+ [--with-doxygen=FILE],
+ [doxygen program to use (eg /usr/bin/doxygen)]),
+ dnl
+ dnl Check the given doxygen program.
+ dnl
+ [DOXYGEN=${withval}
+ AC_CHECK_PROG(
+ [BUILD_DOCS],
+ [${DOXYGEN}],
+ [yes],
+ [no])
+ if test $BUILD_DOCS = no; then
+ echo "WARNING:"
+ echo "The doxygen program you specified:"
+ echo "$DOXYGEN"
+ echo "was not found. Please check the path and make sure "
+ echo "the program exists and is executable."
+ AC_MSG_WARN(
+ [Warning: no doxygen detected. Documentation will not be built])
+ fi],
+ [AC_CHECK_PROG(
+ [BUILD_DOCS],
+ [${DOXYGEN}],
+ [yes],
+ [no])
+ if test ${BUILD_DOCS} = no; then
+ echo "WARNING:"
+ echo "The doxygen program was not found in your execute"
+ echo "You may have doxygen installed somewhere not covered by your path."
+ echo ""
+ echo "If this is the case make sure you have the packages installed, AND"
+ echo "that the doxygen program is in your execute path (see your"
+ echo "shell's manual page on setting the \$PATH environment variable), OR"
+ echo "alternatively, specify the program to use with --with-doxygen."
+ AC_MSG_WARN(
+ [Warning: no doxygen detected. Documentation will not be built])
+ fi])
+ dnl
+ dnl Substitution
+ dnl
+ AC_SUBST([DOXYGEN])
+ AM_CONDITIONAL(BUILD_DOCS, test "x$BUILD_DOCS" = "xyes")
+ ])
+dnl End of acinclude.m4
\ Pas de fin de ligne ? la fin du fichier.
diff --git a/configure.ac b/configure.ac
index 72136cf..9cc8bca 100644
--- a/configure.ac
+++ b/configure.ac
@@ -118,7 +118,9 @@ AC_SUBST(CWARNFLAGS)
GCC_CHECK_VISIBILITY()
-AC_CONFIG_FILES([Makefile src/Makefile tests/Makefile])
+AM_CHECK_DOXYGEN()
+
+AC_CONFIG_FILES([Makefile src/Makefile tests/Makefile doc/Makefile])
AC_CONFIG_FILES([xcb.pc xcb-xlib.pc xcb-composite.pc xcb-damage.pc xcb-dpms.pc xcb-glx.pc xcb-randr.pc xcb-record.pc xcb-render.pc xcb-res.pc xcb-screensaver.pc xcb-shape.pc xcb-shm.pc xcb-sync.pc xcb-xevie.pc xcb-xf86dri.pc xcb-xfixes.pc xcb-xinerama.pc xcb-xprint.pc xcb-xtest.pc xcb-xv.pc xcb-xvmc.pc])
AC_OUTPUT
diff --git a/doc/tutorial/index.html b/doc/tutorial/index.html
index ea53305..1aa6cac 100644
--- a/doc/tutorial/index.html
+++ b/doc/tutorial/index.html
@@ -706,7 +706,7 @@ main ()
}
printf ("\n");
- printf ("Informations of screen %ld:\n", screen->root.xid);
+ printf ("Informations of screen %ld:\n", screen->root);
printf (" width.........: %d\n", screen->width_in_pixels);
printf (" height........: %d\n", screen->height_in_pixels);
printf (" white pixel...: %ld\n", screen->white_pixel);
@@ -723,16 +723,15 @@ main ()
characterized by an Id. So, in XCB, a window is of type:
</p>
<pre class="code">
-typedef struct {
- uint32_t xid;
-} xcb_window_t;
+typedef uint32_t xcb_window_t;
</pre>
<p>
We first ask for a new Id for our window, with this function:
</p>
- <pre class="code">
-xcb_window_t xcb_window_new(xcb_connection_t *c);
-</pre>
+ <a name="generate_id">
+ <pre class="code">
+uint32_t xcb_generate_id (xcb_connection_t *c);
+</pre></a>
<p>
Then, XCB supplies the following function to create new windows:
</p>
@@ -776,7 +775,7 @@ main ()
{
xcb_connection_t *c;
xcb_screen_t *screen;
- xcb_drawable_t win;
+ xcb_window_t win;
/* Open the connection to the X server */
c = xcb_connect (NULL, NULL);
@@ -785,12 +784,12 @@ main ()
screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
/* Ask for our window's Id */
- win.window = xcb_window_new(c);
+ win = xcb_generate_id (c);
/* Create the window */
xcb_create_window (c, /* Connection */
XCB_COPY_FROM_PARENT, /* depth (same as root)*/
- win.window, /* window Id */
+ win , /* window Id */
screen->root, /* parent window */
0, 0, /* x, y */
150, 150, /* width, height */
@@ -800,7 +799,7 @@ main ()
0, NULL); /* masks, not used yet */
/* Map the window on the screen */
- xcb_map_window (c, win.window);
+ xcb_map_window (c, win);
/* Make sure commands are sent before we pause, so window is shown */
xcb_flush (c);
@@ -887,19 +886,14 @@ int xcb_aux_sync (xcb_connection_t *c);
a Graphics Context is, as a window, characterized by an Id:
</p>
<pre class="code">
-typedef struct {
- uint32_t xid;
-} xcb_gcontext_t;
+typedef uint32_t xcb_gcontext_t;
</pre>
<p>
We first ask the X server to attribute an Id to our graphic
- context with this function:
- </p>
- <pre class="code">
-xcb_gcontext_t xcb_gcontext_new (xcb_connection_t *c);
-</pre>
- <p>
- Then, we set the attributes of the graphic context with this function:
+ context with the
+ <span class="code"><a href="#generate_id">xcb_generate_id</a></span>
+ function. Then, we set the attributes of the graphic context
+ with this function:
</p>
<pre class="code">
xcb_void_cookie_t xcb_create_gc (xcb_connection_t *c,
diff --git a/src/xcb.h b/src/xcb.h
index 751bf70..4c3e079 100644
--- a/src/xcb.h
+++ b/src/xcb.h
@@ -112,7 +112,7 @@ typedef struct {
uint8_t pad0; /**< Padding */
uint16_t sequence; /**< Sequence number */
uint32_t pad[7]; /**< Padding */
- uint32_t full_sequence;
+ uint32_t full_sequence; /**< full sequence */
} xcb_generic_event_t;
/**
@@ -125,7 +125,7 @@ typedef struct {
uint8_t error_code; /**< Error code */
uint16_t sequence; /**< Sequence number */
uint32_t pad[7]; /**< Padding */
- uint32_t full_sequence;
+ uint32_t full_sequence; /**< full sequence */
} xcb_generic_error_t;
/**
@@ -217,7 +217,6 @@ xcb_generic_event_t *xcb_wait_for_event(
/**
* @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.
*
@@ -362,10 +361,10 @@ void xcb_disconnect(xcb_connection_t *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.
+ * @param name: The name of the display.
+ * @param host: A pointer to a malloc'd copy of the hostname.
+ * @param display: A pointer to the display number.
+ * @param screen: A pointer to the screen number.
* @return 0 on failure, non 0 otherwise.
*
* Parses the display string name @p display_name in the form
@@ -395,9 +394,9 @@ xcb_connection_t *xcb_connect(const char
/**
* @brief Connects to the X server, using an authorization information.
- * @param displayname: The name of the display.
+ * @param display: The name of the display.
* @param auth: The authorization information.
- * @param screenp: A pointer to a preferred screen number.
+ * @param screen: A pointer to a preferred screen number.
* @return A newly allocated xcb_connection_t structure.
*
* Connects to the X server specified by @p displayname, using the
More information about the Xcb
mailing list