Cómo documentar un objeto de función con doxygen?

¿Cómo debo documentar un objeto de función (un functor AKA) con doxygen? Se siente engañoso simplemente documentarlo como una clase regular. Me parece mucho mejor pensar en un objeto de función como una función con un cierre que una clase invocable.Cómo documentar un objeto de función con doxygen?

¿Hay alguna manera de documentar un objeto de función que se ajuste a mis preferencias?

class Adder 
{ 
public: 
    Adder(size_t x) : 
     m_x(x) 
    { } 

    size_t operator() (size_t y) const 
    { 
     return m_x + y; 
    } 

private: 
    const size_t m_x; 
};

Fuente

2011-03-05 deft_code

que dan cuenta de la primera pregunta es un poco subjetiva. Lo incluí para permitir respuestas que simplemente me dicen que estoy equivocado y para hacerlo de la manera normal (con alguna justificación, espero). La segunda pregunta es mucho más al grano. –

Este código no es válido, debe ser 'operator() (size_t y)' etc. –

Darle documentación de la clase, poner la palabra funtor en la primera frase (preferiblemente como la primera palabra) y evita la documentación operator() si el significado es obvio.

Cuenta: el significado es a menudo no obvio si operator() está sobrecargado.

Fuente

2011-03-05 17:58:14

¿Sugiere que agregue '@param [in] y ...' a la descripción de la clase? –

@deft_code: si necesita '@ param', entonces el significado aparentemente no es obvio. Tiendo a no utilizar tales características, confiando en los nombres de los parámetros descriptivos. –

Idealmente, todas las funciones son lo suficientemente simples y los parámetros tan bien nombrados que su propósito es obvio. Sin embargo, ese no es siempre el caso. Del mismo modo que a veces necesito proporcionar una descripción un poco más profunda de un parámetro de función, es posible que necesite elaborar sobre los parámetros de un objeto de función. –

Puede usar Doxygen member groups para agrupar todos sus funtores. Tal vez algo así podría funcionar:

/// @name Functors 
/// @{ 

class Adder; 

/// @} 

/// Functor that adds a set value to its argument when called. 
class Adder 
{ 
public: 
    Adder(size_t x) : 
     m_x(x) 
    { } 

    size_t operator() (size_t y) const 
    { 
     return m_x + y; 
    } 

private: 
    const size_t m_x; 
};

Fuente

2011-03-25 17:32:44 jakar

La documentación de la clase debería ser suficiente. Simplemente describa los propósitos y el uso y aclare cualquier cosa útil. Se puede evitar una documentación demasiado detallada de lo obvio.

/*! \brief Adder functor 
* 
* Returns size_t sum of const member and parameter 
*/ 
class Adder 
{ 
public: 
    //! Construct with constant value for subsequent sums 
    Adder(size_t x) : 
     m_x(x) 
    { } 

    //! Call with value to compute with constant 
    size_t operator() (size_t y) const 
    { 
     return m_x + y; 
    } 

private: 
    const size_t m_x; 
};

Fuente

2011-03-25 18:04:24 AJG85

Cómo documentar un objeto de función con doxygen?

Respuesta

Cuestiones relacionadas