[PATCH 3/8] doc: Remove wl_map from documentation

[Derek Foreman]

On 21/01/15 11:30 PM, Bill Spitzak wrote:
> Both of \cond changes these are because the current doxygen config turns
> on documentation for all objects whether or not they have doxygen comments.

Ahh, I somehow missed that.

I just sent one of my own for wayland-server.c, because I think it's
pretty silly to have a comment that says "deprecated functions below"
then have a bunch of new not-deprecated functions sneak up at the end...

> You are right they probably could be removed if this was switched and
> comments were added to everything that was wanted. However a previous
> patch I did that did something like that (to add \memberof commands to a
> lot of messages) was rejected, because there was no descriptive text
> added to the docs and it seems better to have it be undocumented until
> somebody actually writes some text.

I can see how that would be problematic.  This solution's looking better
to me now. :)

Reviewed-by: Derek Foreman <derekf at osg.samsung.com>

> On 01/21/2015 07:28 AM, Derek Foreman wrote:
>> On 02/01/15 08:29 PM, Bill Spitzak wrote:
>>> This object is only in wayland-private.h so it's methods should not
>>> be in the documentation.
>>> ---
>>>   src/wayland-util.c |    4 ++++
>>>   1 file changed, 4 insertions(+)
>>>
>>> diff --git a/src/wayland-util.c b/src/wayland-util.c
>>> index b099882..db51ebb 100644
>>> --- a/src/wayland-util.c
>>> +++ b/src/wayland-util.c
>>> @@ -149,6 +149,8 @@ wl_array_copy(struct wl_array *array, struct
>>> wl_array *source)
>>>       return 0;
>>>   }
>>>
>>> +/** \cond */
>>> +
>>
>> There's nothing between the cond and endcond, so this doesn't visible
>> change doc generation today?
>>
>> I'm not sure this is the right thing to do - should we maybe have a
>> separate appendix for private functions instead of just throwing away
>> any doc (assuming it ever exists :)
>>
>> The documentation may be useful to people working on wayland, not just
>> working with wayland...
>>
>>>   union map_entry {
>>>       uintptr_t next;
>>>       void *data;
>>> @@ -361,6 +363,8 @@ wl_map_for_each(struct wl_map *map,
>>> wl_iterator_func_t func, void *data)
>>>       for_each_helper(&map->server_entries, func, data);
>>>   }
>>>
>>> +/** \endcond */
>>> +
>>>   static void
>>>   wl_log_stderr_handler(const char *fmt, va_list arg)
>>>   {
>>>
>>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel