diff --git a/capsule/capsule.h b/capsule/capsule.h index 7badedbe4c07e00ea4b7fd474447dbb28cebf7c3..680d079d8b6b8fb228e0f6564f6040d40a65cb3b 100644 --- a/capsule/capsule.h +++ b/capsule/capsule.h @@ -121,25 +121,34 @@ struct _capsule_metadata _CAPSULE_PUBLIC capsule capsule_init (const char *soname); +//////////////////////////////////////////////////////////////////////////// +// do not move the Returns declaration in this next doc-comment: +// gtk-doc does not tolerate any non-whitespace text between the +// last parameter and the Returns line if the name of the function +// is capsule_shim_dlopen. This was discovered empirically. +// As this is clearly insane, it must be a bad interaction with something +// else which shares some element of that name, but I have no idea what. +//////////////////////////////////////////////////////////////////////////// + /** * capsule_shim_dlopen: * @cap: The capsule from which `dlopen` was called * @file: SONAME or filename to be opened - * @flag: dlopen() flags to pass to the real dlmopen() call + * @flag: `dlopen` flags to pass to the real `dlopen` call * - * An implementation of `dlopen` suitable to be called from inside a - * namespace. Load @file into @cap's namespace. + * An implementation of dlopen suitable to be called from inside a + * namespace. Load @file into @cap namespace. * * If @cap has a non-trivial prefix, load @file and its recursive - * dependencies from @cap's prefix instead of from the root filesystem. + * dependencies from @cap prefix instead of from the root filesystem. * * This helper function exists because dlopen() cannot safely be called * by a DSO opened into a private namespace. It takes @file and @flag - * arguments (cf dlopen()) and a @capsule handle, + * arguments cf dlopen() and a @cap handle, * and performs a safe dlmopen() call instead. * * Typically this function is used to implement a safe wrapper for dlopen() - * which is assigned to the @int_dlopen member of the #capsule_metadata. + * which is assigned to the int_dlopen member of the #capsule_metadata. * This * replaces calls to dlopen() by all DSOs in the capsule, * allowing libraries which use dlopen() to work inside the capsule. *