gtk-doc confused about symbols

[Matthias Clasen-2]

Lately, I notice that gtk-doc throws some odd things into the
-undocumented.txt file, things that don't look like function names,
but rather like the beginning of sentences:

Adds
Adjust
Cancels
Get
...

How does that happen ?


Matthias
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Stefan Kost]

hi,

Matthias Clasen schrieb:

> Lately, I notice that gtk-doc throws some odd things into the
> -undocumented.txt file, things that don't look like function names,
> but rather like the beginning of sentences:
>
> Adds
> Adjust
> Cancels
> Get
> ...
>
> How does that happen ?
>
>  

No idea yet, but I can confirm it. I hope its not related to that glib
still uses tmpl files. I am looking at it now and will commit a fix
later on.

As some good news we'll probably get a build.gnome.org slave that builds
docs using gtk-doc svn trunk.

Stefan

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

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

[Stefan Kost]

Matthias Clasen schrieb:
> Lately, I notice that gtk-doc throws some odd things into the
> -undocumented.txt file, things that don't look like function names,
> but rather like the beginning of sentences:
>  
gtk-doc: Rebuilding template files
cd . && gtkdoc-mktmpl --module=glib
./tmpl/types.sgml:202: warning: Can't parse args for function guint64:
*g_thread_gettime) (void

./tmpl/macros_misc.sgml:406: warning: Can't parse args for function
G_LIKELY: number) ?((GLIB_SIZEOF_LONG * 8 - 1) ^ __builtin_clzl(number))
+ 1 : 1;#elseregister guint n_bits = 0;do{n_bits++;number >>= 1;}while
(number

./glib-sections.txt:1344: warning: No declaration found for: tm
./glib-sections.txt:2640: warning: No declaration found for:
g_test_config_vars

Its was already filed as
http://bugzilla.gnome.org/show_bug.cgi?id=532395

Would be good if you guys could start to get rid of some of the
warnings. I'll try to improve the parser to handle these.

Stefan

> Adds
> Adjust
> Cancels
> Get
> ...
>
> How does that happen ?
>
>
> Matthias
> _______________________________________________
> gtk-doc-list mailing list
> gtk-doc-list@...
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list
>  

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

[Stefan Kost]

hi,

glib has probably copied code from somewhere that uses /** but not
follows the gtk-doc syntax.
I temporily added the locations where the things are found to the output
(see attached file). Should be easy to fix.
Either make them follow the gtk-doc syntax or change the comment into /*.

Stefan

Matthias Clasen schrieb:

> Lately, I notice that gtk-doc throws some odd things into the
> -undocumented.txt file, things that don't look like function names,
> but rather like the beginning of sentences:
>
> Adds
> Adjust
> Cancels
> Get
> ...
>
> How does that happen ?
>
>
> Matthias
> _______________________________________________
> gtk-doc-list mailing list
> gtk-doc-list@...
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list
>  

99% symbol docs coverage.
3367 symbols documented.
7 symbols incomplete.
30 not documented.


Adds
        2b: defined at ../../../gio/inotify/inotify-helper.c:107
Adjust
        2b: defined at ../../../gio/fen/fen-data.c:389
Cancels
        2b: defined at ../../../gio/inotify/inotify-helper.c:122
GIOFlags (G_IO_FLAG_MASK, G_IO_FLAG_GET_MASK, G_IO_FLAG_SET_MASK)
        0: defined at ./tmpl/iochannels.sgml:517
GIOFuncs (io_read, io_write, io_seek, io_close, io_create_watch, io_free, io_set_flags, io_get_flags)
        0: defined at ./tmpl/iochannels.sgml:455
GPollFD (fd, fd, events, revents)
        0: defined at ./tmpl/main.sgml:701
GScanner (user_data, max_parse_errors, parse_errors, input_name, qdata, config, symbol_table, input_fd, text, text_end, buffer, scope_id)
        0: defined at ./tmpl/scanner.sgml:26
GScannerConfig (cset_skip_characters, cset_identifier_first, cset_identifier_nth, cpair_comment_single, case_sensitive, skip_comment_multi, skip_comment_single, scan_comment_multi, scan_identifier, scan_identifier_1char, scan_identifier_NULL, scan_symbols, scan_binary, scan_octal, scan_float, scan_hex, scan_hex_dollar, scan_string_sq, scan_string_dq, numbers_2_int, int_2_float, identifier_2_string, char_2_token, symbol_2_token, scope_0_fallback, store_int64, padding_dummy)
        0: defined at ./tmpl/scanner.sgml:69
GSourceFuncs (closure_callback, closure_marshal)
        0: defined at ./tmpl/main.sgml:763
GThreadFunctions (mutex_new, mutex_lock, mutex_trylock, mutex_unlock, mutex_free, cond_new, cond_signal, cond_broadcast, cond_wait, cond_timed_wait, cond_free, private_new, private_get, private_set, thread_create, thread_yield, thread_join, thread_exit, thread_set_priority, thread_self, thread_equal)
        0: defined at ./tmpl/threads.sgml:137
G_HAVE_GNUC_VISIBILITY
        2b: defined at ./tmpl/macros_misc.sgml:356
G_PASTE_ARGS
        2b: defined at ./tmpl/macros_misc.sgml:117
Get
        2b: defined at ../../../gio/fen/fen-kernel.c:479
_g_local_directory_monitor_new
        2b: defined at ../../../gio/glocaldirectorymonitor.c:254
_g_local_file_new
        2b: defined at ../../../gio/glocalfile.c:319
_g_mount_get_for_mount_path
        2b: defined at ../../../gio/gunionvolumemonitor.c:568
_g_unix_volume_monitor_lookup_volume_for_mount_path
        2b: defined at ../../../gio/gunixvolumemonitor.c:289
_g_win32_mount_new
        2b: defined at ../../../gio/gwin32mount.c:127
_g_winhttp_file_new
        2b: defined at ../../../gio/win32/gwinhttpfile.c:85
delete
        2b: defined at ../../../gio/fen/fen-node.c:280
depth
        2b: defined at ../../../gio/fen/fen-node.c:421
fdata_add_event
        2b: defined at ../../../gio/fen/fen-data.c:594
g_dummy_file_new
        2b: defined at ../../../gio/gdummyfile.c:113
g_io_channel_error_quark
        2b: defined at ../../../glib/giochannel.c:2381
g_local_file_input_stream_new
        2b: defined at ../../../gio/glocalfileinputstream.c:121
g_local_file_monitor_new
        2b: defined at ../../../gio/glocalfilemonitor.c:178
g_unix_volume_disconnected
        2b: defined at ../../../gio/gunixvolume.c:163
g_unix_volume_monitor_new
        2b: defined at ../../../gio/gunixvolumemonitor.c:228
g_unix_volume_new
        2b: defined at ../../../gio/gunixvolume.c:113
g_unix_volume_set_mount
        2b: defined at ../../../gio/gunixvolume.c:179
g_unix_volume_unset_mount
        2b: defined at ../../../gio/gunixvolume.c:203
g_winhttp_file_input_stream_new
        2b: defined at ../../../gio/win32/gwinhttpfileinputstream.c:98
g_winhttp_file_output_stream_new
        2b: defined at ../../../gio/win32/gwinhttpfileoutputstream.c:95


gfilterinputstream:Long_Description
gfilteroutputstream:Long_Description
shell:Long_Description
spawn:Long_Description

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

[David Nečas (Yeti)-2]

On Mon, Jan 26, 2009 at 11:03:37AM +0200, Stefan Kost wrote:
> glib has probably copied code from somewhere that uses /** but not
> follows the gtk-doc syntax.
> I temporily added the locations where the things are found to the output
> (see attached file). Should be easy to fix.
> Either make them follow the gtk-doc syntax or change the comment into /*.

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?

Yeti

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

[David Nečas (Yeti)-2]

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).

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@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Owen Taylor]

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@...
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list

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

[David Nečas (Yeti)-2]

Forgot to Cc the list?

On Mon, Jan 26, 2009 at 04:31:31PM +0200, Stefan Kost wrote:
> I would love to just apply this. In the past people have wanted gtk-doc
> to still accept all kind of broken syntax.

That's why I was very conservative, I did not evne actually add the
colon requirement, just required that the regexp matched the complete
line.  That is

/**
 * Blah

will still match but at least

/**
 * Blah blah blah

will not.

Regarding the warnings, ignoring a malformed documentation comment means
missing documentation which will be reported (that is, once we fix the
undocumented symbol checks).  If anyone cares at least a little bit
this can be easily noticed.  If no one cares, I am not sure gtk-doc
should really care.

The sad truth is that warnings are ignored as long as the tool produces
the expected output.

Yeti

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

[Stefan Kost]

David Nečas schrieb:

> 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).
>
> 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";
>      }
>
>  

Matthias, how does this sound. We take anything that is one word
followed by a ':' or not as a symbol and I remove the warning about
"Symbol name not found at the start of the comment block.".
We should probably also only look for the symbol name before anything else.

Or would yo like to keep it as it is and turning the /** into /* comments?

Stefan
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Matthias Clasen-2]

On Thu, Jan 29, 2009 at 5:14 AM, Stefan Kost <ensonic@...> wrote:

> David Nečas schrieb:
>> 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).
>>
>> 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";
>>           }
>>
>>
> Matthias, how does this sound. We take anything that is one word
> followed by a ':' or not as a symbol and I remove the warning about
> "Symbol name not found at the start of the comment block.".
> We should probably also only look for the symbol name before anything else.
>
> Or would yo like to keep it as it is and turning the /** into /* comments?

Having that warning sounds good. I also regularly remove the extra *
from stuff thats not supposed to be a doc comment, but thats an uphill
battle and new ones keep crawling in...
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[David Nečas (Yeti)-2]

Stefan, did you really mean

--- trunk/gtkdoc-mkdb.in 2009/01/29 22:25:15 673
+++ trunk/gtkdoc-mkdb.in 2009/02/05 15:04:08 675
@@ -3405,7 +3408,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";
     }

in this commit

http://svn.gnome.org/viewvc/gtk-doc/trunk/gtkdoc-mkdb.in?r1=673&r2=675

?

Because this change does not change anything, both regular expressions
match the same lines.   I originally suggested to require that the line
ends after the semicolon (sans whitespace), but you do not have the $
there.

Yeti

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

[Stefan Kost]

David Nečas schrieb:

> Stefan, did you really mean
>
> --- trunk/gtkdoc-mkdb.in 2009/01/29 22:25:15 673
> +++ trunk/gtkdoc-mkdb.in 2009/02/05 15:04:08 675
> @@ -3405,7 +3408,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";
>      }
>
> in this commit
>
> http://svn.gnome.org/viewvc/gtk-doc/trunk/gtkdoc-mkdb.in?r1=673&r2=675
>
> ?
>
> Because this change does not change anything, both regular expressions
> match the same lines.   I originally suggested to require that the line
> ends after the semicolon (sans whitespace), but you do not have the $
> there.
>
> Yeti
>

Sorry, my mistake, fixed in svn.

Stefan
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list