WARNING: Inline literal start-string without end-string.

[xypron]

I am using Sphinx to create HTML documentation for project U-Boot (http://git.denx.de/u-boot.git). The documentation is created via

make htmldocs

The documentation for some functions is rendered incorrectly.

File lib/efi_loader/efi_boottime.c has the following:

/**
 * efi_create_event() - create an event
 * @type:            type of the event to create
 * @notify_tpl:      task priority level of the event
 * @notify_function: notification function of the event
 * @notify_context:  pointer passed to the notification function
 * @group:           event group
 * @event:           created event
 *
 * This function is used inside U-Boot code to create an event.
 *
 * For the API function implementing the CreateEvent service see
 * efi_create_event_ext.
 *
 * Return: status code
 */
efi_status_t efi_create_event(uint32_t type, efi_uintn_t notify_tpl,
                              void (EFIAPI *notify_function) (
                                        struct efi_event *event,
                                        void *context),
                              void *notify_context, efi_guid_t *group,
                              struct efi_event **event)
{

This produces a warning:

./lib/efi_loader/efi_boottime.c:583: WARNING: Inline literal start-string without end-string.
./lib/efi_loader/efi_boottime.c:583: WARNING: Inline emphasis start-string without end-string.
./lib/efi_loader/efi_boottime.c:583: WARNING: Inline emphasis start-string without end-string.
./lib/efi_loader/efi_boottime.c:583: WARNING: Inline emphasis start-string without end-string.

The parameter notfiy_function is rendered as:

``void (EFIAPI *notify_function) ( struct efi_event *event, void *context) ``
    undescribed

Why is the warning thrown?
Why is the parameter description missing?
Why do I get the superfluous ``?

Best regards

Heinrich Schuchardt

[stephenfin]

I'm guessing you meant to report this against https://github.com/sphinx-doc/sphinx, which is where the core functionality for sphinx-apidoc lives. This is only an extension for that. However, I would suggest contacting the U-Boot developers directly as they have set this up and likely understand how it works better than anyone.

[xypron]

The problem was in a script built around sphinx. See: https://lkml.org/lkml/2018/9/3/1185