GNOME Bugzilla – Bug 441979
Warn if a function appears without "()" in docs
Last modified: 2018-05-22 13:01:17 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.
Clearly Enhancement.
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.
agreed about max, but not MAX ;). I'd be happy enough if this is done for symbols with at least one underscore.
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).
Yeah, it makes most sense for the symbols in current library. Extra points for adding checks for %NULL, %TRUE, and %FALSE by default.
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
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?
-- 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.