Re: Lines starting with "returns"

[Matthias Clasen <maclas gmx de>]

Am Son, 2002-04-28 um 18.36 schrieb Owen Taylor:
> 
> 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?

This form will of course continue to work. What my patch adds is a way
out of the trap of lines in the description inadvertedly being
interpreted by gtk-doc as start of the return value description, because
they start with "returns". The safe way is to specify the return value
as part of the parameter list as @returns:. 
We have had a number of bug reports about incomplete function
documentation ending in the middle of the sentence where the next word
would have been "returns"...