After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 441979 - Warn if a function appears without "()" in docs
Warn if a function appears without "()" in docs
Status: RESOLVED OBSOLETE
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal enhancement
: ---
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2007-05-29 04:46 UTC by Behdad Esfahbod
Modified: 2018-05-22 13:01 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Behdad Esfahbod 2007-05-29 04:46:31 UTC
The odds that I write pango_layout_set_text in pango docs and I didn't meant pango_layout_set_text() are really slim.  It would be a lot more helpful if gtk-doc warned about such uses.
Comment 1 Behdad Esfahbod 2007-05-29 04:46:50 UTC
Clearly Enhancement.
Comment 2 Yeti 2007-09-04 19:05:15 UTC
For pango_layout_set_text the chances might be slim, for MAX perhaps not... I wonder if this can be done without the introduction of a special markup with the only purpose to suppress such warnings.
Comment 3 Behdad Esfahbod 2007-09-04 19:14:25 UTC
agreed about max, but not MAX ;).  I'd be happy enough if this is done for symbols with at least one underscore.
Comment 4 Stefan Sauer (gstreamer, gtkdoc dev) 2007-09-07 17:59:31 UTC
If we're doing that should we also warn if camel-case words miss a # and all caps words with underscores miss a %. I think its a good idea, but might be a feature that some people would like to turn off.

Would it make sense to differenciate between symbols in the libarry we're just building the docs for. There we know the symbols, so a warning could be justified. For links to external symbols we can't check that easily at the scanning time (links would be removed if they can't be resolved by fixxref - so a link to much would not hurt).
Comment 5 Behdad Esfahbod 2007-09-07 19:34:25 UTC
Yeah, it makes most sense for the symbols in current library.  Extra points for adding checks for %NULL, %TRUE, and %FALSE by default.
Comment 6 Behdad Esfahbod 2008-01-29 21:05:01 UTC
FWIW, I added a very extensive and ugly test to cairo to check for these kind of stuff.  It lives in cairo/src/check-doc-syntax.sh.  Here it is:

#!/bin/sh

LANG=C

if ! grep --version 2>/dev/null | grep GNU >/dev/null; then
	echo "GNU grep not found; skipping test"
	exit 0
fi

test -z "$srcdir" && srcdir=.
status=0

echo Checking documentation for incorrect syntax

# Note: this test is also run from doc/public/ to check the SGML files

if test "x$SGML_DOCS" = x; then
	FILES="$cairo_all_source_file"
	if test "x$FILES" = x; then
		FILES=`find "$srcdir" -name '*.h' -or -name '*.c' -or -name '*.cpp'`
	fi
fi

enum_regexp='\([^%@]\|^\)\<\(FALSE\|TRUE\|NULL\|CAIRO_[0-9A-Z_]*[^(0-9A-Z_]\)'
if test "x$SGML_DOCS" = x; then
	enum_regexp='^[/ ][*] .*'$enum_regexp
fi
if grep "$enum_regexp" $FILES | grep -v '#####'; then
	status=1
	echo Error: some macros in the docs are not prefixed by percent sign.
	echo Fix this by searching for the following regexp in the above files:
	echo "	'$enum_regexp'"
fi

type_regexp='\( .*[^#]\| \|^\)\<cairo[0-9a-z_]*_t\>\($\|[^:]$\|[^:].\)'
if test "x$SGML_DOCS" = x; then
	type_regexp='^[/ ][*]'$type_regexp
else
	type_regexp='\(.'$type_regexp'\)\|\('$type_regexp'.\)'
fi
if grep "$type_regexp" $FILES | grep -v '#####'; then
	status=1
	echo Error: some type names in the docs are not prefixed by hash sign,
	echo neither are the only token in the doc line followed by colon.
	echo Fix this by searching for the following regexp in the above files:
	echo "	'$type_regexp'"
fi

func_regexp='\([^#]\|^\)\<\(cairo_[][<>/0-9a-z_]*\> \?[^][ <>(]\)'
if test "x$SGML_DOCS" = x; then
	func_regexp='^[/ ][*] .*'$func_regexp
fi
if grep "$func_regexp" $FILES | grep -v '#####'; then
	status=1
	echo Error: some function names in the docs are not followed by parentheses.
	echo Fix this by searching for the following regexp in the above files:
	echo "	'$func_regexp'"
fi

note_regexp='NOTE'
if grep "$note_regexp" $FILES; then
	status=1
	echo Error: some source files contain the string 'NOTE'.
	echo Be civil and replace it by 'Note' please.
fi

exit $status
Comment 7 Benjamin Otte (Company) 2009-11-15 22:50:10 UTC
I'm not exactly sure a warning is a good idea.
If gtk-doc knows that they should be marked up, why doesn't it just mark them up?
Comment 8 GNOME Infrastructure Team 2018-05-22 13:01:17 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/5.