Comment dois-je documenter un objet de fonction (AKA Foncteur) avec DOXYGEN? Il se sent trompeur pour simplement le documenter comme une classe normale. Je trouve beaucoup mieux de penser à un objet de fonction en fonction d'une fermeture qu'une classe appelable.
existe un moyen de documenter un objet de fonction qui convient à mes préférences? P>
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;
};
3 Réponses :
Donnez la documentation de la classe informatique, mettez le mot foncteur dans la première phrase (de préférence comme le premier mot) et ignorez la documentation Mind You: La signification est souvent si le sens est évident.
opérateur () est surchargé.
Vous suggérez-vous d'ajouter @param [in] y ... dans la description de la classe?
@deft_code: Si vous avez besoin @param , la signification n'est apparemment pas évidente. J'ai tendance à ne pas utiliser de telles fonctionnalités, en s'appuyant à la place des noms de paramètres descriptifs.
Idéalement, toutes les fonctions sont assez simples et les paramètres si bien nommés que leur but est évident. Cependant ce n'est pas toujours le cas. Tout comme parfois, je dois fournir une description légèrement plus approfondie d'un paramètre de fonction, je devra peut-être élaborer des paramètres d'objets de fonction.
@deft_code: Documez ensuite le but global du fonctionnement dans les documents de la classe et n'explique que sur les arguments dans opérateur () docs. Il n'est pas utile de le décrire davantage avec "appeler le foncteur" ou similaire, car cela est évident du nom.
Vous pouvez utiliser DOXYGEN Groupes membres pour regrouper tous vos fonctions ensemble . Peut-être que quelque chose comme ça fonctionnerait:
La documentation de classe devrait suffire. Décrivez simplement les objectifs et l'utilisation et clarifiez tout ce qui est utile. La documentation excessivement verbeuse de l'évidence peut être évitée.
/*! \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;
};
Je réalise que la première question est un peu subjective. Je l'ai inclus pour permettre des réponses qui me disent simplement que je me trompe et de le faire de la voie normale (avec une justification que j'espère). La deuxième question est beaucoup plus au point.
Ce code est invalide, il devrait être
opérateur () (taille_t y) etc.