Re: Lines starting with "returns"

[Damon Chaplin <damon ximian com>]

On Sun, 2002-04-28 at 12:36, Owen Taylor wrote:
> 
> Matthias Clasen <maclas gmx de> writes:
> 
> > Here is a patch to fix #65997. It changes the source scanning of gtk-doc
> > to ignore lines starting with "returns" when the return value was
> > already specified as @returns: in the parameter section. 
> 
> What about the template that the commonly used emacs macro
> produces:
> 
> /**
>  * gtk_window_get_title:
>  * @window: a #GtkWindow
>  *
>  * Retrieves the title of the window. See gtk_window_set_title().
>  *
>  * Return value: the title of the window, or %NULL if none has
>  *    been set explicitely. The returned string is owned by the widget
>  *    and must not be modified or freed.
>  **/
> 
> Where the return value is specified as "Return value:" and
> after the parameter section. Can we do anything about that?
> 
> (Or does it just work since the Return Value: section is after?
> Haven't checked recently.)

I don't think the patch affects those. All the patch does is set
$ignore_returns if it finds a 'Returns:' field in the top part.
Then it won't look for 'Returns' any more.


If gtk-doc finds 2 'Returns' descriptions, after the parameter
descriptions, it assumes the first one was the main function description
and the second one was the return value description, so it should work.
i.e. something like:

/**
 * gtk_window_get_title:
 * @window: a #GtkWindow
 *
 * Returns the title of the window. See gtk_window_set_title().
 *
 * Return value: the title of the window, or %NULL if none has
 *    been set explicitely. The returned string is owned by the widget
 *    and must not be modified or freed.
 **/

Damon