web-dev-qa-db-fra.com

Quelle est la bonne façon de référencer un paramètre dans Doxygen?

J'ai la documentation Doxygen suivante pour une fonction:

/**
  @brief Does interesting things

  @param[in]  pfirst The first parameter: a barrel full of monkeys

  @pre
    "pfirst" must have been previously passed through BarrelFiller()
*/

Notez que pfirst est un paramètre et qu'il est référencé dans les conditions préalables.

Je l'ai entouré de guillemets ici parce que je veux le tenir à l'écart du reste du texte. Mais ce serait bien de faire cela de telle manière que Doxygen mettra en évidence la commande et, de préférence, la liera à la définition du paramètre. Y a-t-il un moyen de faire cela?

Il serait particulièrement agréable que cela se produise en utilisant uniquement la configuration par défaut (ou des modifications mineures de celle-ci).

doxygen
53
Richard

Doxygen fournit la commande \p pour indiquer que le prochain mot est un paramètre de la fonction. Vous l'utiliseriez ainsi:

... the \p x and \p y coordinates are used to ...

Je crois que par défaut, cela sera représenté en utilisant une police de machine à écrire. Je ne pense pas que cela offre actuellement une fonctionnalité de liaison automatique, mais pourrait le faire à l'avenir.

Il existe une commande associée, \a utilisé pour baliser les arguments des membres. Par défaut, il s'affiche en surbrillance dans le texte (<em>arg</em>)

Vous pouvez trouver plus d'informations sur les différents Doxygen Référence des commandes spéciales .

62
DRH

Je sais que vous posez des questions sur @parameters, mais les recherches Google mènent ici pour @return types aussi, voici donc cette réponse:

Doxygen # utilisation devant la valeur de retour pour créer un lien hypertexte vers sa définition:

Utilisez le # symbole.

Exemple complet ( voir le @return types juste en dessous avec un # devant chacun d'eux ):

#include <stdarg.h> // for va_list, va_start, va_end
#include <stdio.h>  // for vsnprintf

// Function prototype:

int debug_printf(const char *format, ...) __attribute__((format(printf, 1, 2)));

// Function definition:

/// @brief      Function to print out data through serial UART for debugging
/// @param[in]  format  `printf`-like format string
/// @param[in]  ...     `printf`-like variadic list of arguments corresponding to the format string
/// @return     Number of characters printed if OK, or < 0 if error:
///             - #DEBUG_ERR_ENCODING
///             - #DEBUG_ERR_OVERFLOW
///             - #DEBUG_ERR_UART
int debug_printf(const char *format, ...)
{
    int num_chars_printed;

    va_list args;
    va_start(args, format);

    // Use `vsnprintf()` now here to format everything into a single string buffer, then send 
    // out over the UART
    // - num_chars_printed could be set to one of the error codes listed above here

    va_end(args);

    return num_chars_printed;
}

La sortie Doxygen affiche désormais les types de retour d'erreur sous la forme d'une liste de sous-puces sous la ligne Number of characters printed if OK, or < 0 if error:, et chacun des types d'erreur est transformé en URL vers leurs définitions respectives en raison de # caractère devant .

Références Doxygen:

  1. Voir @ la réponse de Jeremy Sarao , et les connaissances tribales qui courent autour de ma tête.
  2. Connaissance tribale. Je ne sais pas comment ni où trouver ces informations. dans la documentation de Doxygen.

Autres références

  1. Documentation pour l'attribut de format printf super utile de GCC:
    1. https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - voir la section "format"
    2. Comment utiliser les chaînes de formatage dans les fonctions définies par l'utilisateur?
    3. Comment utiliser correctement __attribute__ ((format (printf, x, y))) dans une méthode de classe en C++?
  2. Implémentation de base de l'enveloppe printf: https://github.com/adafruit/ArduinoCore-samd/blob/master/cores/arduino/Print.cpp#L189
1
Gabriel Staples

utilisez le symbole "#" devant le paramètre que vous souhaitez référencer:

#pfirst must have been previously passed through BarrelFiller()

( dans le manuel doxygen )

1
Jeremy Sarao