J'abandonne enfin la taxe sur le support d'angle infligée par Microsoft's XML Documentation Format (et quel est le point, puisque l'environnement MSVC reste ne fait rien de fantaisie avec elle pour les projets C ++ ) et changer mon projet actuel pour utiliser Doxygen avec une syntaxe de style Javadoc. C'est fantastique. La documentation en ligne est beaucoup plus facile à lire et à taper, et la sortie générée est tellement plus utile et polyvalente. En particulier, j'ai le Cela me donne exactement la sortie que je désire, tout en maintenant le nombre de méta-commandes bruyantes comme La sortie générée n'interprète pas le deuxième paragraphe dans le J'ai essayé d'ajouter A Tout en recherchant cela, j'ai vu que quelqu'un d'autre avait dupliqué la commande que < EM> Est-ce que produit la sortie que je désire. Les deux paragraphes sont imbriqués dans des balises Y a-t-il une façon standard de faire cela qui me manque? Je ne suis sûrement pas la première personne à vouloir plusieurs Les paragraphes dans la section "remarques" de ma documentation ... et ce n'est pas limité au J'ai la dernière version de Doxygen installé (1.8.2), mais je doute beaucoup que ce soit spécifique à la version. multiline_cpp_is_brief option tournée sur, ce qui me permet d'écrire aussi longtemps qu'une "brève" description que je veux, puis rompez la documentation "Détails" dans les paragraphes à l'aide de lignes vierges. En d'autres termes: @brief et < code> \ Détails que je dois utiliser. @Remarks Section Dans le cadre des remarques. Je peux dire car il n'est pas indenté au même niveau dans la sortie HTML, et ce n'est pas localisé sous le @par commande au début du deuxième paragraphe, mais cela n'a pas fait ce que je voulais non plus. Le nouveau paragraphe n'est toujours pas un enfant de la section "remarques". Dans la sortie XML, il est placé à l'intérieur d'un nouveau @remarks @Remarks ; La même chose se passe avec @Internal , pour Exemple.
4 Réponses :
Votre code d'exemple final, c'est est exactement l'utilisation attendue de Démarre un paragraphe où une ou plusieurs remarques peuvent être entrées. Le paragraphe sera en retrait. Le texte du paragraphe n'a pas de structure interne spéciale. Toutes les commandes d'amélioration visuelle peuvent être utilisées à l'intérieur du paragraphe. Plusieurs commandes donc Vous avez raison de dire que ce comportement n'est pas limité à \ remarques pour les blocs de commentaires multi-paragraphes. Du DOXYGEN manual (emphase mine):
\ remarque {Texte de remarque}
\ remarque seront jointes à un paragraphe unique. Chaque remarque commencera sur une nouvelle ligne. Alternativement, une commande \ remarque peut mentionner plusieurs remarques. La commande \ remarque lorsqu'une ligne vierge ou une autre commande de section de section est rencontrée.
\ remarque (et \ remarques , qui est juste la même que \ remarque ) se termine à la fin de un paragraphe, mais adjacent \ remarque s sera cousu ensemble pour former un \ remarque bloc. \ remarques et \ remarque . Il en va de même pour toute commande qui prend un paragraphe de texte sous forme d'argument, voir, par exemple, \ bug , \ todo , \ avertissement c.
Hmm ouais j'ai lu ça, mais la première partie en gras est exactement ce qui m'a confondu. Il est indiqué que les commandes multiples adjacentes \ remarque seront conjointement dans un paragraphe unique . Ce n'est pas ce que je veux. Je veux Séparer les paragraphes . Mais ensuite, la phrase suivante continue à dire que "chaque remarque commencera sur une nouvelle ligne", il s'agit probablement d'un bug de documentation. Il devrait probablement dire "bloc" ou "section", plutôt que "paragraphe". Bon à savoir que c'est la solution officielle, bien que je pense toujours que cela ressemble à une erreur.
Tu as raison, j'ai négligé ça. Je pense que ce doit être juste une erreur de documentation, compte tenu du comportement que vous mentionnez dans la question. C'est pourquoi je pense qu'il est moins déroutant d'utiliser \ remarque , plutôt que \ remarques . Si vous n'aimez pas la façon dont la documentation a l'air de laisser tomber le \ remarques tout à fait ou combinez les deux remarques en un: c.-à-d. \ remarque Notez que cette fonction est réentrante, mais pas le fil -en sécurité! Si la sécurité du thread est requise, l'utilisateur doit gérer le verrouillage et le déverrouillage manuellement de la région.
En effet, taper \ remarque me fait ressentir un peu mieux à ce sujet. Merci pour le conseil!
Une solution qui semble fonctionner que je n'ai pas vu mentionné ici, est de terminer vos lignes avec \ n. Cela gardera tout ce qui est regroupé, tout en mettant dans l'espace blanc que vous voudrez peut-être voir.
Si vous voulez une ligne vide, assurez-vous que la ligne ci-dessus a \ n et que vous avez une ligne vide avec \ n dessus.
Dans votre exemple, vous voudriez: et cela devrait l'apparaître comme vous le souhaitez.
De même, vous pouvez séparer des paragraphes avec des balises de
.
C'était comme ça que j'ai travaillé autour d'un bug Doxygen lié à l'utilisation de @parblock Intérieur @todo comme moyen de mettre des listes à bulleted à l'intérieur des TODOS. (Le @endparBlock clouerait l'implicite "fin TODO", produisant une sortie de page "TODODDO" cassée.)
Les solutions peuvent être généralisées (DOXYGEN 1.8.9.1). J'ai utilisé: kjka4wbasj6
Les trois paragraphes sont en retrait et le titre est imprimé en caractères gras au-dessus d'eux. Bien sûr, \ par titre peut être remplacé par \ remarque . La phrase magique est le \ n à la fin des paragraphes et les lignes vides peuvent être insérés éventuellement. Non \ n est requis dans les lignes vides. Malheureusement, je n'ai pas trouvé de moyen d'ajouter un autre paragraphe de texte indenté après la section Code.
Si vous n'aimez pas avoir plusieurs lignes de @Remarks dans votre source pour vos remarques multi-paragraphes, je pense que vous pouvez utiliser @parBlock & @endparBlock pour inclure plusieurs paragraphes pour un seul @Remark.