Re: gtk-doc confused about symbols

[Owen Taylor <otaylor redhat com>]

On Mon, 2009-01-26 at 10:45 +0100, David Nečas wrote:
> On Mon, Jan 26, 2009 at 10:23:14AM +0100, David Nečas wrote:
> > Should the parser really consume this?
> > 
> > /**
> >  * Adds a subscription to be monitored.
> >  */ 
> > 
> > The first line is not an identifier followed by a colon, so it cannot be
> > a symbol documentation.  Or is such a vague matching necessary for some
> > legacy documentation?
> 
> I mean something like this (I would even remove the warning about
> comments where we cannot find a symbol because if there is no symbol the
> comment is not intended for our consumption).

We're having bad experiences with gobject-introspection where it
silently ignores a /** comment that is missing the colon. It's not
user-friendly behavior. You could, I suppose, try to catch whether it
looks "strongly" like a function doc comment, or and not warn on
something like the above, but warn on:

 /**
  * my_func
  * ....

But that might just be too magic.

- Owen

> Index: gtkdoc-mkdb.in
> ===================================================================
> --- gtkdoc-mkdb.in	(revision 665)
> +++ gtkdoc-mkdb.in	(working copy)
> @@ -3397,7 +3397,7 @@
>  		$symbol = $1;
>  		#print "SECTION DOCS found in source for : '$symbol'\n";
>  		$ignore_broken_returns = 1;
> -	    } elsif (m%^\s*([\w:-]*\w)\s*:?%) {
> +	    } elsif (m%^\s*([\w:-]*\w)\s*:?\s*$%) {
>  		$symbol = $1;
>  		#print "SYMBOL DOCS found in source for : '$symbol'\n";
>  	    }

> 
> Yeti
> 
> _______________________________________________
> gtk-doc-list mailing list
> gtk-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list