glibc/manual/check-deftype.sh

51 lines
1.8 KiB
Bash
Raw Normal View History

manual: Fix and test @deftypef* function formatting The manual contained several instances of incorrect formatting that were correct texinfo but produced incorrectly rendered manuals or incorrect behaviour from the tooling. The most important was incorrect quoting of function returns by failing to use {} to quote the return. The impact of this mistake means that 'info libc func' does not jump to the function in question but instead to the introductory page under the assumption that func doesn't exist. The function returns are now correctly quoted. The second issue was the use of a category specifier with @deftypefun which doesn't accept a category specifier. If a category specifier is required then @deftypefn needs to be used. This is corrected by changing the command to @deftypefn for such functions that used {Deprecated function} as a category. The last issue is a missing space between the function name and the arguments which results in odd function names like "epoll_wait(int" instead of "epoll_wait". This also impacts the use of 'info libc' and is corrected. We additionally remove ';' from the end of function arguments and add an 'int' return type for dprintf. Lastly we add a new test check-deftype.sh which verifies the expected formatting of @deftypefun, @deftypefunx, @deftypefn, and @deftypefnx. The new test is also run as the summary file is generated to ensure we don't generate incorrect results. The existing check-safety.sh is also run directly as a test to increase coverage since the existing tests only ran on manual install. The new tests now run as part of the standard "make check" that pre-commit CI runs and developers should run. No regressions on x86_64. HTML and PDF rendering reviewed and looks correct for all changes. Reviewed-by: H.J. Lu <hjl.tools@gmail.com>
2024-10-10 06:32:26 +08:00
#!/bin/sh
# Copyright 2024 Free Software Foundation, Inc.
# This file is part of the GNU C Library.
# The GNU C Library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
# The GNU C Library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
# You should have received a copy of the GNU Lesser General Public
# License along with the GNU C Library; if not, see
# <https://www.gnu.org/licenses/>.
# Check that the @deftypefun command is called with the expected
# arguments and includes checking for common mistakes including
# failure to include a space after the function name, or incorrect
# quoting.
success=:
# If no arguments are given, take all *.texi files in the current directory.
test $# != 0 || set *.texi
# We search for all @deftypefun and @deftypefunx command uses.
# Then we remove all of those that match our expectations.
# A @deftypefun or @deftypefunx command takes 3 arguments:
# - return type
# - name
# - arguments
# This is different from @deftypefn which includes an additional
# category which is implicit here.
grep -n -r '^@deftypefun' "$@" |
grep -v '^.*@deftypefunx\?'\
' \({\?[a-zA-Z0-9_ *]*}\?\) \([a-zA-Z0-9_]*\) (.*)$' &&
success=false
# We search for all @deftypefn and @deftypefnx command uses.
# We have 4 arguments in the command including the category.
grep -n -r '^@deftypefn' "$@" |
grep -v '^.*@deftypefnx\?'\
' {\?[a-zA-Z ]*}\? \({\?[a-zA-Z0-9@{}_ *]*}\?\) \([a-zA-Z0-9_]*\) (.*)$' &&
success=false
$success