javadoc en C++
qdii
générer de la documentation à la facon de la javadoc ? . J'entends par là
qu'une série de commentaire (@parm, @return, ...) rajoutée au header
permet à un parser de générer une doc html plus lisible.
--
qdii
Fabien LE LEZ
>Petite question facile : Quel outil utilisez-vous / conseillez-vous pour
>g�n�rer de la documentation � la facon de la javadoc ?
Doxygen ?
Richard Delorme
+1
--
Richard
James Kanze
Doxygen est de loin le plus connu et le plus utilisé. Il est
nettement plus souple que JavaDoc, mais il souffre du même
défaut de base : il commence par les sources, pour en générer la
documentation, et non vice versa.
--
James Kanze
qdii
> il commence par les sources, pour en générer la documentation, et non
> vice versa.
Je ne vois pas comment, à partir d'une documentation (qui ne fournit
qu'une interface) on pourrait générer un code source o_O ?
--
qdii
Fabien LE LEZ
<james...@gmail.com>:
>mais il souffre du m�me
>d�faut de base : il commence par les sources, pour en g�n�rer la
>documentation, et non vice versa.
Ce n'est pas vraiment un probl�me incoutournable. Chez moi, j'ai des
fichiers source, des fichiers texte contenant la doc, et un petit
script qui cr�e des "sources comment�s" dans un format compatible
Doxygen. �a marche tr�s bien, d'autant que Doxygen indique quand mes
docs ne sont plus � jour.
Richard Delorme
qdii
> http://www-cs-faculty.stanford.edu/~knuth/cweb.html
Ce lien est extrêmement commercial est très peu explicatif.
J'y ai appris qu'avec CWEB je coderai de facon meilleure, je débuggerai
mieux, et je produirai une documentation dernier-cri...
Si mes rivaux utilisent CWEB et pas moi, mon entreprise se fera bouffer.
Cela dit il fournit une traduction en russe et coréen du manuel
d'utilisateur, alors je ne peux que te remercier de me l'avoir fourni :)
--
qdii
Fabien LE LEZ
>Si mes rivaux utilisent CWEB et pas moi, mon entreprise se fera bouffer.
Je me demande s'il existe un produit vaguement informatique dont
l'argumentaire marketing ne contient pas cette affirmation...
James Kanze
Ça dépend de la documentation. De toute façon, sans que
l'information qui doit se trouver dans la documentation est
figée (et la meilleur façon de la figer, c'est de l'écrire noir
sur blanc), tu ne peux pas commencer la programmation. En ce qui
concerne la partie OO, une documentation graphique est souvent
plus expressive ; j'ai eu de bonnes expériences avec Rationale
Rose dans la passée. Mais il faut en général une partie texte
aussi ; on peut y en ajouter dans Rose, mais ce n'est peut-être
pas aussi commode que d'autres systèmes, genre cweb. L'idéale,
ça serait une fusion des deux ; en attendant, j'utiliserais Rose
(ou quelque chose de semblable) pour les couches supérieures, où
le OO prédomine, et cweb pour les couches inférieures, où on a
peu de rélations entre les classes (et le contrat devient le
plus important).
--
James Kanze
James Kanze
> >http://www-cs-faculty.stanford.edu/~knuth/cweb.html
> Ce lien est extrêmement commercial est très peu explicatif.
C'est la page d'accueil. Est-ce que tu connais une page
d'accueil qui n'est pas comme ça ? Le seul vrai problème avec la
page que je vois (mais c'est assez fréquent aussi), c'est qu'il
n'amème pas à une documentation plus détaillée en ligne ; il
faut que tu télécharges le produit, et lire la documentation
compris là.
> J'y ai appris qu'avec CWEB je coderai de facon meilleure, je
> débuggerai mieux, et je produirai une documentation
> dernier-cri...
Comme avec tout outil qui se respecte:-).
En fait, où j'aurais des doutes (peut-être), c'est « Produce
state-of-the-art documentation ». State-of-the-art
documentation, c'est du HTML, non du LaTeX. (En revanche, si le
but est lisibilité et compréhensibilité, plutôt que d'être
state-of-the-art à tout prix, LaTeX n'est pas forcément un
mauvais choix pour l'ensemble.)
La clé, c'est la phrase qui suit : « The main idea is to regard
a program as a communication to human beings rather than as a
set of instructions to a computer. » Indépendamment de l'outil,
c'est un but essentiel.
--
James Kanze
Jean-Marc Bourguet
> On Nov 1, 8:34 am, qdii <q...@reblochon.be> wrote:
> > >http://www-cs-faculty.stanford.edu/~knuth/cweb.html
>
> > Ce lien est extr�mement commercial est tr�s peu explicatif.
>
> C'est la page d'accueil. Est-ce que tu connais une page d'accueil qui
> n'est pas comme �a ? Le seul vrai probl�me avec la page que je vois (mais
> c'est assez fr�quent aussi), c'est qu'il n'am�me pas � une documentation
> plus d�taill�e en ligne�; il faut que tu t�l�charges le produit, et lire
> la documentation compris l�.
>
> > J'y ai appris qu'avec CWEB je coderai de facon meilleure, je d�buggerai
> > mieux, et je produirai une documentation dernier-cri...
>
> Comme avec tout outil qui se respecte:-).
Ne pas oublier que DEK a aussi un certain sens de l'humour.
> En fait, o� j'aurais des doutes (peut-�tre), c'est ��Produce
> state-of-the-art documentation��. State-of-the-art documentation, c'est
> du HTML, non du LaTeX. (En revanche, si le but est lisibilit� et
> compr�hensibilit�, plut�t que d'�tre state-of-the-art � tout prix, LaTeX
> n'est pas forc�ment un mauvais choix pour l'ensemble.)
J'ai deja genere du HTML a partir de LaTeX (voir par exemple
http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu
avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de
le regarder source mais j'utilise cela pour des documents que je concois
comme a imprimer).
Je suis quasiment certain que CWEB ne genere pas du LaTeX, ce doit etre du
plain TeX si ce n'est pas un format expres fait par DEK. Il doit aussi
etre possible de generer du HTML, mais je ne sais pas au prix de quel
effort d'adaptation de TeX4ht
Sur le fond, j'ai deja experimente avec quelques variantes d'outils de
programmation litteraire et genere du HTML avec certains d'entre eux. Ca
me semble bien dans un objectif de publication d'algorithme ou de cours de
programmation, mais pas particulierement pour un gros programme destine a
la production. Je prefere doxygen pour cela. Si j'ai bonne memoire, ma
preference allais a noweb.
A+
--
Jean-Marc
FAQ de fclc++: http://www.cmla.ens-cachan.fr/~dosreis/C++/FAQ
C++ FAQ Lite en VF: http://www.ifrance.com/jlecomte/c++/c++-faq-lite/index.html
Site de usenet-fr: http://www.usenet-fr.news.eu.org
Falk Tannhäuser
> J'ai deja genere du HTML a partir de LaTeX (voir par exemple
> http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu
> avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de
> le regarder source mais j'utilise cela pour des documents que je concois
> comme a imprimer).
Dans le temps il y avait aussi LaTeX2HTML <http://www.latex2html.org/>,
mais il semble mort :-(
Falk
Jean-Marc Bourguet
Si j'ai bonne memoire, il fonctionnait suivant un autre principe que
TeX4ht. Ce dernier interprete le dvi (et donc n'a a priori pas de
problemes avec les macros TeX, mais utilise des specials ou qqch du genre
pour marquer ce qu'il doit traiter specialement), latex2html avait une
connaissance de LaTeX, mais avait des problemes des qu'on utilisait une
macro dont il n'avait pas connaissance.
Il y a bien sur aussi la methode inverse, utiliser un autre markup et
generer du html ou du LaTeX a partir de ca.
James Kanze
> James Kanze <james.ka...@gmail.com> writes:
> > On Nov 1, 8:34 am, qdii <q...@reblochon.be> wrote:
> > > >http://www-cs-faculty.stanford.edu/~knuth/cweb.html
[...]
> > En fait, où j'aurais des doutes (peut-être), c'est « Produce
> > state-of-the-art documentation ». State-of-the-art
> > documentation, c'est du HTML, non du LaTeX. (En revanche, si
> > le but est lisibilité et compréhensibilité, plutôt que
> > d'être state-of-the-art à tout prix, LaTeX n'est pas
> > forcément un mauvais choix pour l'ensemble.)
> J'ai deja genere du HTML a partir de LaTeX (voir par
> exemplehttp://www.bourguet.org/v2/cs/charset/, il y a un lien
> vers un PDF obtenu avec la meme source -- comme beaucoup de
> HTML genere, on n'a pas envie de le regarder source mais
> j'utilise cela pour des documents que je concois comme a
> imprimer).
En effet. D'après mes expériences (très limitées), ça peut
servir pour donner une prévue sur le Web d'un document imprimé,
mais l'orientation reste imprimé. Actuellement, ou bien
j'utilise plutôt pdflatex, pour générer du PDF, et je laisse
tomber l'HTML, ou bien, j'écris directement en HTML.
> Je suis quasiment certain que CWEB ne genere pas du LaTeX, ce
> doit etre du plain TeX si ce n'est pas un format expres fait
> par DEK.
Peut-être bien. Je n'ai jamais eu l'occasion de l'utiliser
réelement.
> Il doit aussi etre possible de generer du HTML, mais je ne
> sais pas au prix de quel effort d'adaptation de TeX4ht
Au fond, on doit pouvoir développer quelque chose de semblable
directement en HTML ou XML, a peu d'efforts si on dispose déjà
d'un parseur XML. Mais éditer l'XML ou le HTML directement dans
un éditeur, c'est encore plus pénible que d'éditer le LaTeX.
> Sur le fond, j'ai deja experimente avec quelques variantes
> d'outils de programmation litteraire et genere du HTML avec
> certains d'entre eux. Ca me semble bien dans un objectif de
> publication d'algorithme ou de cours de programmation, mais
> pas particulierement pour un gros programme destine a la
> production. Je prefere doxygen pour cela. Si j'ai bonne
> memoire, ma preference allais a noweb.
Le problème de base, quelque soit le système (y compris
Doxygen), c'est que tu es obligé de t'occuper du balisage au
même temps que tu saisis le texte, et que le balisage apparaît
(et distrait) dans les fichiers source. Et que quand tu fais de
la maintenance, c'est en fin de compte les fichiers source que
tu as devant les yeux. Pour la saisie initiale, j'ai d'assez
bonne expérience avec vim en mode texte, avec un programme
filtre qui convertit en commentaires Doxygen par la suite.
(C'est le programme « comment » sur ma site. Sous vim, je me
mets dans une mode texte, sans indentation automatique, pour
saisir le texte, puis je le passe par « comment », et je me mets
en mode C++ pour saisir le code. Mais c'est une solution d'assez
bas niveau ; ça marche bien plur les bibliothèques qui sont
pratiquement une collection des classes plus ou moins
indépendantes, mais ça ne suffit pas du tout pour l'application,
où il faut documenter les relations entre les classes.)
--
James Kanze