Re: [PATCH 5/6] utils: Ensure wl_list's doxygen formats properly
On Sun, Sep 15, 2013 at 01:37:10PM -0500, Aaron Faanes wrote:
This changes the struct foo mentions to use tt, which appears as
monospaced font. This also wraps code examples with \code tags to
ensure they're detected as code.
Is there a doxygen markup we can use instead of tt? Most of the
tt uses are for types that doxygen should have a tag for, I
believe. And if we have to use html, maybe code is better?
The code example uses C++ style // comments. I would have preferred to
use /* */ comments for consistency, but this is not possible since we're
already in this type of block comment. Doxygen picks it up fine,
however.
Perhaps we could use #47; instead of a literal / ?
This commit doesn't contain any changes in terms of wording. Most of the
diff noise is due to the whitespace changes. git diff -w should help
point out the real changes.
---
src/wayland-util.h | 44 +---
1 file changed, 25 insertions(+), 19 deletions(-)
diff --git a/src/wayland-util.h b/src/wayland-util.h
index 31a1ac2..51de3f6 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -70,39 +70,45 @@ struct wl_interface {
*
* \brief doubly-linked list
*
- * The list head is of struct wl_list type, and must be initialized
- * using wl_list_init(). All entries in the list must be of the same
- * type. The item type must have a struct wl_list member. This
- * member will be initialized by wl_list_insert(). There is no need to
- * call wl_list_init() on the individual item. To query if the list is
- * empty in O(1), use wl_list_empty().
+ * The list head is of ttstruct wl_list/tt type, and must be initialized
+ * using #wl_list_init. All entries in the list must be of the same
+ * type. The item type must have a ttstruct wl_list/tt member. This
+ * member will be initialized by #wl_list_insert. There is no need to
+ * call #wl_list_init on the individual item. To query if the list is
+ * empty in O(1), use #wl_list_empty.
*
- * Let's call the list reference struct wl_list foo_list, the item type as
- * item_t, and the item member as struct wl_list link.
+ * Let's call the list reference ttstruct wl_list foo_list/tt, the item
type as
+ * ttitem_t/tt, and the item member as ttstruct wl_list link/tt.
*
* The following code will initialize a list:
*
- * struct wl_list foo_list;
+ * \code
+ * struct wl_list foo_list;
*
- * struct item_t {
- * int foo;
- * struct wl_list link;
- * };
- * struct item_t item1, item2, item3;
+ * struct item_t {
+ * int foo;
+ * struct wl_list link;
+ * };
+ * struct item_t item1, item2, item3;
*
- * wl_list_init(foo_list);
- * wl_list_insert(foo_list, item1.link); Pushes item1 at the head
- * wl_list_insert(foo_list, item2.link); Pushes item2 at the head
- * wl_list_insert(item2.link, item3.link); Pushes item3 after item2
+ * wl_list_init(foo_list);
+ * wl_list_insert(foo_list, item1.link); // Pushes item1 at the head
+ * wl_list_insert(foo_list, item2.link); // Pushes item2 at the head
+ * wl_list_insert(item2.link, item3.link); // Pushes item3 after item2
+ * \endcode
*
- * The list now looks like [item2, item3, item1]
+ * The list now looks like tt[item2, item3, item1]/tt
*
* Will iterate the list in ascending order:
*
+ * \code
* item_t *item;
* wl_list_for_each(item, foo_list, link) {
* Do_something_with_item(item);
* }
+ * \endcode
+ *
+ * \sa wl_container_of
*/
struct wl_list {
struct wl_list *prev;
--
1.8.3.1
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH 5/6] utils: Ensure wl_list's doxygen formats properly
On Tue, Sep 17, 2013 at 12:09 AM, Kristian Høgsberg hoegsb...@gmail.comwrote:
On Sun, Sep 15, 2013 at 01:37:10PM -0500, Aaron Faanes wrote:
This changes the struct foo mentions to use tt, which appears as
monospaced font. This also wraps code examples with \code tags to
ensure they're detected as code.
Is there a doxygen markup we can use instead of tt? Most of the
tt uses are for types that doxygen should have a tag for, I
believe. And if we have to use html, maybe code is better?
For a single word, Doxygen's \c would be used, but it doesn't extend beyond
that word. Doxygen recommended tt for multi-word code, so I naively went
with it without thought. :)
Digging into it, a better option could be backticks, as they behave like
code blocks. This is a Markdown-inspired feature added to Doxygen[1] in
~April 2012; I mention this in case there's a preference for supporting old
Doxygens.
In any case, the actual struct or class will be linked up if it has
documentation. The backticks are solely for monospacing the struct prefix.
The code example uses C++ style // comments. I would have preferred to
use /* */ comments for consistency, but this is not possible since we're
already in this type of block comment. Doxygen picks it up fine,
however.
Perhaps we could use #47; instead of a literal / ?
Unfortunately, it doesn't seem possible to get Doxygen not to escape the
ampersand in #47; unless it's within a \htmlonly block. On top of that, a
\code block disables Doxygen commands, so \htmlonly sadly isn't available.
The good news is I came up with a hackish solution I found to get /* */
output properly in HTML, XML, and manpages (and probably the other
formats). The trick is using ~~~ (another Markdown feature) for code
blocks, instead of \code, and defining a Doxygen alias to output a
specially crafted string:
* ~~~
* struct wl_listener your_listener;
* your_listener.notify = your_callback_method;
*
* \comment{Direct access}
* wl_signal_add(some_object-destroy_signal, your_listener);
*
* \comment{Accessor access}
* wl_event_loop *loop = ...;
* wl_event_loop_add_destroy_listener(loop, your_listener);
* ~~~
ALIASES += comment{1}=/* \1 *!-- --/
So the trade-off here is that the output is correct and consistent, but
there's a bit of weirdness on the input side. If this sounds reasonable,
I'll rework my patches to use it instead of the C++ style.
-- Aaron
[1] - Markdown features in Doxygen:
http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
--
Aaron Faanes dafr...@gmail.com
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH 5/6] utils: Ensure wl_list's doxygen formats properly
On Tue, Sep 17, 2013 at 1:47 AM, Aaron Faanes dafr...@gmail.com wrote:
On Tue, Sep 17, 2013 at 12:09 AM, Kristian Høgsberg hoegsb...@gmail.com
wrote:
On Sun, Sep 15, 2013 at 01:37:10PM -0500, Aaron Faanes wrote:
This changes the struct foo mentions to use tt, which appears as
monospaced font. This also wraps code examples with \code tags to
ensure they're detected as code.
Is there a doxygen markup we can use instead of tt? Most of the
tt uses are for types that doxygen should have a tag for, I
believe. And if we have to use html, maybe code is better?
For a single word, Doxygen's \c would be used, but it doesn't extend beyond
that word. Doxygen recommended tt for multi-word code, so I naively went
with it without thought. :)
Digging into it, a better option could be backticks, as they behave like
code blocks. This is a Markdown-inspired feature added to Doxygen[1] in
~April 2012; I mention this in case there's a preference for supporting old
Doxygens.
In any case, the actual struct or class will be linked up if it has
documentation. The backticks are solely for monospacing the struct prefix.
The code example uses C++ style // comments. I would have preferred to
use /* */ comments for consistency, but this is not possible since we're
already in this type of block comment. Doxygen picks it up fine,
however.
Perhaps we could use #47; instead of a literal / ?
Unfortunately, it doesn't seem possible to get Doxygen not to escape the
ampersand in #47; unless it's within a \htmlonly block. On top of that, a
\code block disables Doxygen commands, so \htmlonly sadly isn't available.
The good news is I came up with a hackish solution I found to get /* */
output properly in HTML, XML, and manpages (and probably the other formats).
The trick is using ~~~ (another Markdown feature) for code blocks, instead
of \code, and defining a Doxygen alias to output a specially crafted string:
* ~~~
* struct wl_listener your_listener;
* your_listener.notify = your_callback_method;
*
* \comment{Direct access}
* wl_signal_add(some_object-destroy_signal, your_listener);
*
* \comment{Accessor access}
* wl_event_loop *loop = ...;
* wl_event_loop_add_destroy_listener(loop, your_listener);
* ~~~
ALIASES += comment{1}=/* \1 *!-- --/
So the trade-off here is that the output is correct and consistent, but
there's a bit of weirdness on the input side. If this sounds reasonable,
I'll rework my patches to use it instead of the C++ style.
I think that all sounds fine. Thanks for digging into this.
Kristian
-- Aaron
[1] - Markdown features in Doxygen:
http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
--
Aaron Faanes dafr...@gmail.com
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH 5/6] utils: Ensure wl_list's doxygen formats properly
Doxygen itself can parse nested C comments. So a solution I found is this: #ifdef THIS_IS_NOT_DEFINED /** This is some documentation. * Example: * \code * /* look this is a c-style comment! */ * \endcode */ #endif Unfortunately, it doesn't seem possible to get Doxygen not to escape the ampersand in #47; unless it's within a \htmlonly block. On top of that, a \code block disables Doxygen commands, so \htmlonly sadly isn't available. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
[PATCH 5/6] utils: Ensure wl_list's doxygen formats properly
This changes the struct foo mentions to use tt, which appears as
monospaced font. This also wraps code examples with \code tags to
ensure they're detected as code.
The code example uses C++ style // comments. I would have preferred to
use /* */ comments for consistency, but this is not possible since we're
already in this type of block comment. Doxygen picks it up fine,
however.
This commit doesn't contain any changes in terms of wording. Most of the
diff noise is due to the whitespace changes. git diff -w should help
point out the real changes.
---
src/wayland-util.h | 44 +---
1 file changed, 25 insertions(+), 19 deletions(-)
diff --git a/src/wayland-util.h b/src/wayland-util.h
index 31a1ac2..51de3f6 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -70,39 +70,45 @@ struct wl_interface {
*
* \brief doubly-linked list
*
- * The list head is of struct wl_list type, and must be initialized
- * using wl_list_init(). All entries in the list must be of the same
- * type. The item type must have a struct wl_list member. This
- * member will be initialized by wl_list_insert(). There is no need to
- * call wl_list_init() on the individual item. To query if the list is
- * empty in O(1), use wl_list_empty().
+ * The list head is of ttstruct wl_list/tt type, and must be initialized
+ * using #wl_list_init. All entries in the list must be of the same
+ * type. The item type must have a ttstruct wl_list/tt member. This
+ * member will be initialized by #wl_list_insert. There is no need to
+ * call #wl_list_init on the individual item. To query if the list is
+ * empty in O(1), use #wl_list_empty.
*
- * Let's call the list reference struct wl_list foo_list, the item type as
- * item_t, and the item member as struct wl_list link.
+ * Let's call the list reference ttstruct wl_list foo_list/tt, the item
type as
+ * ttitem_t/tt, and the item member as ttstruct wl_list link/tt.
*
* The following code will initialize a list:
*
- * struct wl_list foo_list;
+ * \code
+ * struct wl_list foo_list;
*
- * struct item_t {
- * int foo;
- * struct wl_list link;
- * };
- * struct item_t item1, item2, item3;
+ * struct item_t {
+ * int foo;
+ * struct wl_list link;
+ * };
+ * struct item_t item1, item2, item3;
*
- * wl_list_init(foo_list);
- * wl_list_insert(foo_list, item1.link); Pushes item1 at the head
- * wl_list_insert(foo_list, item2.link); Pushes item2 at the head
- * wl_list_insert(item2.link, item3.link); Pushes item3 after item2
+ * wl_list_init(foo_list);
+ * wl_list_insert(foo_list, item1.link); // Pushes item1 at the head
+ * wl_list_insert(foo_list, item2.link); // Pushes item2 at the head
+ * wl_list_insert(item2.link, item3.link); // Pushes item3 after item2
+ * \endcode
*
- * The list now looks like [item2, item3, item1]
+ * The list now looks like tt[item2, item3, item1]/tt
*
* Will iterate the list in ascending order:
*
+ * \code
* item_t *item;
* wl_list_for_each(item, foo_list, link) {
* Do_something_with_item(item);
* }
+ * \endcode
+ *
+ * \sa wl_container_of
*/
struct wl_list {
struct wl_list *prev;
--
1.8.3.1
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
