empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] #6960

thosoo · 2023-01-24T11:02:46Z

Summary

Hi,
I am trying to compile mbedtls as cmake submodule inside the hyperion.ng project in a termux environment on android.
Initially I asked the hyperion devs for help, but I got forwarded here, as it is only a submodule.
During compilation I get the following errors:

[ 15%] Building C object dependencies/external/mbedtls/library/CMakeFiles/mbedcrypto.dir/base64.c.o
In file included from /data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/library/base64.c:25:
In file included from /data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/library/constant_time_internal.h:30:
In file included from /data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/library/ssl_misc.h:27:
In file included from /data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/mbedtls/ssl.h:35:
In file included from /data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/mbedtls/x509_crt.h:27:
In file included from /data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/mbedtls/legacy_or_psa.h:104:
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_SUCCESS
   ~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:92:41: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:93:42: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:94:43: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:95:38: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_HARDWARE_FAILURE
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:96:41: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:97:42: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:98:37: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_STORAGE_FAILURE
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:99:34: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_DATA_INVALID
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:100:34: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_DATA_CORRUPT
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:371:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_SUCCESS
   ~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:372:36: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_INVALID_HANDLE
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:373:41: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:374:43: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:375:41: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:376:37: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_STORAGE_FAILURE
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:377:34: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_DATA_CORRUPT
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:378:34: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_ERROR_DATA_INVALID
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:489:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_SUCCESS
   ~~~~~~~~~~~~~~~~~~~^
fatal error: too many errors emitted, stopping now [-ferror-limit=]
20 errors generated.
make[2]: *** [dependencies/external/mbedtls/library/CMakeFiles/mbedcrypto.dir/build.make:160: dependencies/external/mbedtls/library/CMakeFiles/mbedcrypto.dir/base64.c.o] Error 1
make[1]: *** [CMakeFiles/Makefile2:1209: dependencies/external/mbedtls/library/CMakeFiles/mbedcrypto.dir/all] Error 2
make[1]: *** Waiting for unfinished jobs....

The only solution I have found through google was to disable -Wdocumentation, which does not seem like a correct solution.

System information

Mbed TLS version (number or commit id): 3.3
Operating system and version: Termux (Android)
Configuration (if not default, please attach mbedtls_config.h): none?
Compiler and options (if you used a pre-built binary, please indicate how you obtained it):
clang 15.0.7
cmake source code:

cmake_minimum_required(VERSION 3.2)

		set(CMAKE_POLICY_DEFAULT_CMP0071 NEW)

		set(DEFAULT_USE_SYSTEM_MBEDTLS_LIBS OFF CACHE BOOL "system mbedtls libraries not found, disable use system mbedtls libraries")
		set(BUILD_SHARED_LIBS OFF CACHE BOOL "Build shared mbedtls libraries")

		set(ENABLE_TESTING OFF CACHE BOOL "Disable mbedTLS tests")
		set(GEN_FILES OFF CACHE BOOL "Disable mbedTLS auto-generated files")
		set(ENABLE_PROGRAMS OFF CACHE BOOL "Disable mbedTLS programs")
		#set(LINK_WITH_PTHREAD ON CACHE BOOL "Enable mbedTLS library linked to pthread.")

		set(USE_SHARED_MBEDTLS_LIBRARY OFF CACHE BOOL "Disable mbedTLS shared libraries")
		set(USE_STATIC_MBEDTLS_LIBRARY ON CACHE BOOL "Enable mbedTLS static libraries")

		set(MBEDTLS_DOWNLOAD_DIR "${CMAKE_BINARY_DIR}/dependencies/external/mbedtls/download")
		set(MBEDTLS_SOURCE_DIR "${CMAKE_SOURCE_DIR}/dependencies/external/mbedtls")
		set(MBEDTLS_BINARY_DIR "${CMAKE_BINARY_DIR}/dependencies/external/mbedtls/build")
		set(MBEDTLS_INSTALL_DIR "${CMAKE_BINARY_DIR}")
		if(${CMAKE_BUILD_TYPE} AND ${CMAKE_BUILD_TYPE} EQUAL "Debug")
			set(MBEDTLS_LOGGING 1)
		else ()
			set(MBEDTLS_LOGGING 0)
		endif ()

		add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/external/mbedtls)

		set (MBEDTLS_INCLUDE_DIR "${MBEDTLS_SOURCE_DIR}/include")
		set (MBEDTLS_INCLUDE_DIR ${MBEDTLS_INCLUDE_DIR} PARENT_SCOPE)
		if (MBEDTLS_INCLUDE_DIR)
			if (EXISTS "${MBEDTLS_INCLUDE_DIR}/mbedtls/build_info.h")
				file(STRINGS ${MBEDTLS_INCLUDE_DIR}/mbedtls/build_info.h _MBEDTLS_VERSION_LINE REGEX "^#define[ \t]+MBEDTLS_VERSION_STRING[\t ].*")
				string(REGEX REPLACE ".*MBEDTLS_VERSION_STRING[\t ]+\"(.*)\"" "\\1" MBEDTLS_VERSION ${_MBEDTLS_VERSION_LINE})
				set (MBEDTLS_VERSION ${MBEDTLS_VERSION} PARENT_SCOPE)
				message(STATUS "Using static mbedtls libraries (build version \"${MBEDTLS_VERSION}\")")
			elseif(EXISTS "${MBEDTLS_INCLUDE_DIR}/mbedtls/version.h")
				file(STRINGS "${MBEDTLS_INCLUDE_DIR}/mbedtls/version.h" _MBEDTLS_VERSION_STRING REGEX "^#[\t ]*define[\t ]+MBEDTLS_VERSION_STRING[\t ]+\"[0-9]+.[0-9]+.[0-9]+\"")
				string(REGEX REPLACE "^.*MBEDTLS_VERSION_STRING.*([0-9]+.[0-9]+.[0-9]+).*" "\\1" MBEDTLS_VERSION "${_MBEDTLS_VERSION_STRING}")
				set (MBEDTLS_VERSION ${MBEDTLS_VERSION} PARENT_SCOPE)
				message(STATUS "Using static mbedtls libraries (build version \"${MBEDTLS_VERSION}\")")
			endif()
		endif ()

		include_directories(${MBEDTLS_INCLUDE_DIR})

		if(WIN32)
			set (MBEDTLS_LIB_INSTALL_DIR_WITH_LIB_PREFIX "${MBEDTLS_INSTALL_DIR}/lib/${CMAKE_CFG_INTDIR}/")
		else()
			set (MBEDTLS_LIB_INSTALL_DIR_WITH_LIB_PREFIX "${MBEDTLS_INSTALL_DIR}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}")
		endif ()

		set (MBEDTLS_SSL_LIBRARY "${MBEDTLS_LIB_INSTALL_DIR_WITH_LIB_PREFIX}mbedtls${CMAKE_STATIC_LIBRARY_SUFFIX}")
		set (MBEDTLS_X509_LIBRARY "${MBEDTLS_LIB_INSTALL_DIR_WITH_LIB_PREFIX}mbedx509${CMAKE_STATIC_LIBRARY_SUFFIX}")
		set (MBEDTLS_CRYPTO_LIBRARY "${MBEDTLS_LIB_INSTALL_DIR_WITH_LIB_PREFIX}mbedcrypto${CMAKE_STATIC_LIBRARY_SUFFIX}")
		set (MBEDTLS_LIBRARIES ${MBEDTLS_SSL_LIBRARY} ${MBEDTLS_X509_LIBRARY} ${MBEDTLS_CRYPTO_LIBRARY})
		set (MBEDTLS_LIBRARIES ${MBEDTLS_LIBRARIES} PARENT_SCOPE)

		if(${CMAKE_BUILD_TYPE} AND ${CMAKE_BUILD_TYPE} EQUAL "Debug")
			message(STATUS "mbedtls libraries: ${MBEDTLS_LIBRARIES}")
		endif ()

		mark_as_advanced (MBEDTLS_INCLUDE_DIR MBEDTLS_LIBRARIES MBEDTLS_SSL_LIBRARY MBEDTLS_X509_LIBRARY MBEDTLS_CRYPTO_LIBRARY)

Additional environment information:

Expected behavior

No errors.

Actual behavior

/data/data/com.termux/files/home/hyperion/dependencies/external/mbedtls/include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
 * \retval #PSA_SUCCESS
   ~~~~~~~~~~~~~~~~~~~^

Steps to reproduce

Inside Termux on Android:

# install dependencies
pkg install x11-repo
pkg install git cmake build-essential libjpeg-turbo python qt5-qtbase qt5-qmake qt5-qtserialport xrandr xcb-util-image qt5-qtx11extras libjpekg-turbo libusb xcb-util dbus openssl ndk-multilib
# build hyperion
git clone -b mbedtls --recursive https://github.com/Lord-Grey/hyperion.ng.git hyperion
cd hyperion
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="${PREFIX}" ..
make -j $(nproc)

Additional information

The text was updated successfully, but these errors were encountered:

gilles-peskine-arm · 2023-01-24T11:29:36Z

I can reproduce locally with

make CFLAGS='-Wdocumentation -Wno-documentation-deprecated-sync -Werror' CC=clang-15 lib

Passing up to Clang 14, failing with 15.0.6 or 16.0.0.

This looks to me like a bug in Clang ≥15. It insists on having a non-empty description after \return, \retval VALUE or param NAME. But the Doxygen documentation says that the {description} runs to the end of the paragraph and doesn't say that it can't be empty, and the doxygen tool is happy with our code.

paul-elliott-arm · 2023-01-24T12:20:59Z

I suspect we are going to have to disable this warning and suggest you do likewise, at least for the time being (as Gilles points out, our documentation is checked with doxygen anyway)

Apologies, we had not yet encountered this as the most up to date clang in most distributions is still 14.

gilles-peskine-arm · 2023-01-26T15:52:45Z

I've filed a bug/feature request against clang: llvm/llvm-project#60315

Uj947nXmRqV2nRaWshKtHzTvckUUpD · 2023-01-26T23:04:09Z

is there any workaround to be able to build with later clang (eg. 15.0.7)?

tom-cosgrove-arm · 2023-01-26T23:08:35Z

Yes, you can either use make or you can remove -Wdocumentation from the set(CMAKE_C_FLAGS... lines in library/CMakeLists.txt and tests/CMakeLists.txt, which is being done by @paul-elliott-arm in PR 6966 (which is currently in review).

Uj947nXmRqV2nRaWshKtHzTvckUUpD · 2023-01-27T00:20:42Z

on clean git clone, make gives this error:

...........................
CC ../3rdparty/everest/library/everest.c
CC ../3rdparty/everest/library/x25519.c
CC ../3rdparty/everest/library/Hacl_Curve25519_joined.c
AR libmbedcrypto.a
make[1]: ar: No such file or directory
make[1]: *** [Makefile:276: libmbedcrypto.a] Error 127
make[1]: Leaving directory '/data/data/com.termux/files/home/downloads/mbedtls/library'
make: *** [Makefile:18: lib] Error 2

tom-cosgrove-arm · 2023-01-27T07:45:12Z

make[1]: ar: No such file or directory

That is your problem. ar is the standard *nix program to create and maintain library archives (.a files).

After compilation, CMake would have tried to do this too.

You need to ensure that ar is available on your PATH. If your build system needs something other than ar to build archives, you should run make AR=/path/to/program instead.

Uj947nXmRqV2nRaWshKtHzTvckUUpD · 2023-01-27T19:34:30Z

i use termux on an android and managed to install ar with: pkg install binutils-is-llvm
now the build finalizes just fine. Thank you !

Fixes Mbed-TLS#6960 Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

…#6960)

paul-elliott-arm self-assigned this Jan 24, 2023

paul-elliott-arm added the bug label Jan 24, 2023

paul-elliott-arm mentioned this issue Jan 25, 2023

Remove -Wdocumentation from Clang builds #6966

Closed

3 tasks

paul-elliott-arm linked a pull request Jan 25, 2023 that will close this issue

Remove -Wdocumentation from Clang builds #6966

Closed

3 tasks

gilles-peskine-arm mentioned this issue Jan 26, 2023

clang -Wdocumentation is too picky about empty paragraph llvm/llvm-project#60315

Open

paul-elliott-arm mentioned this issue Feb 13, 2023

Backport 2.28 : Remove -wDocumentation from Clang builds #7092

Closed

3 tasks

gilles-peskine-arm mentioned this issue Feb 14, 2023

Avoid empty \retval in Doxygen documentation to pacify Clang 15 #7096

Closed

gilles-peskine-arm mentioned this issue Feb 14, 2023

Pacify Clang 15 about empty \retval #7098

Merged

3 tasks

tom-cosgrove-arm mentioned this issue Feb 21, 2023

Compilation failure due to invalid doc strings #7146

Closed

paul-elliott-arm closed this as completed in #7098 Feb 24, 2023

paul-elliott-arm closed this as completed in 4386cf1 Feb 24, 2023

gilles-peskine-arm added a commit to gilles-peskine-arm/mbedtls that referenced this issue Feb 24, 2023

Changelog entry for pacifying clang -Wdocumentation about \retval

44fe5ea

Fixes Mbed-TLS#6960 Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

sergio-nsk pushed a commit to sergio-nsk/mbedtls that referenced this issue May 29, 2023

Fix documentation warnings when -DMBEDTLS_FATAL_WARNINGS=ON (Mbed-TLS…

23c54cb

…#6960)

matetothpal mentioned this issue Jun 1, 2023

Empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] #7675

Closed

kevleyski mentioned this issue Dec 5, 2023

(macOS) mbedtls dep failure shaka-project/shaka-packager#1314

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] #6960

empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] #6960

thosoo commented Jan 24, 2023 •

edited

Loading

gilles-peskine-arm commented Jan 24, 2023

paul-elliott-arm commented Jan 24, 2023

gilles-peskine-arm commented Jan 26, 2023

Uj947nXmRqV2nRaWshKtHzTvckUUpD commented Jan 26, 2023

tom-cosgrove-arm commented Jan 26, 2023 •

edited

Loading

Uj947nXmRqV2nRaWshKtHzTvckUUpD commented Jan 27, 2023 •

edited

Loading

tom-cosgrove-arm commented Jan 27, 2023

Uj947nXmRqV2nRaWshKtHzTvckUUpD commented Jan 27, 2023

empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] #6960

empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] #6960

Comments

thosoo commented Jan 24, 2023 • edited Loading

Summary

System information

Expected behavior

Actual behavior

Steps to reproduce

Additional information

gilles-peskine-arm commented Jan 24, 2023

paul-elliott-arm commented Jan 24, 2023

gilles-peskine-arm commented Jan 26, 2023

Uj947nXmRqV2nRaWshKtHzTvckUUpD commented Jan 26, 2023

tom-cosgrove-arm commented Jan 26, 2023 • edited Loading

Uj947nXmRqV2nRaWshKtHzTvckUUpD commented Jan 27, 2023 • edited Loading

tom-cosgrove-arm commented Jan 27, 2023

Uj947nXmRqV2nRaWshKtHzTvckUUpD commented Jan 27, 2023

thosoo commented Jan 24, 2023 •

edited

Loading

tom-cosgrove-arm commented Jan 26, 2023 •

edited

Loading

Uj947nXmRqV2nRaWshKtHzTvckUUpD commented Jan 27, 2023 •

edited

Loading