Petite question facile : Quel outil utilisez-vous / conseillez-vous pour
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.
Petite question facile : Quel outil utilisez-vous / conseillez-vous pour générer de la documentation à la facon de la javadoc ?
Doxygen ?
+1
-- Richard
James Kanze
On Oct 31, 12:13 am, qdii wrote:
Petite question facile : Quel outil utilisez-vous / conseillez-vous pour 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.
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
On Oct 31, 12:13 am, qdii <q...@reblochon.be> wrote:
Petite question facile : Quel outil utilisez-vous /
conseillez-vous pour 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.
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.
Petite question facile : Quel outil utilisez-vous / conseillez-vous pour 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.
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
El Sat, 31 Oct 2009 04:41:21 -0700, James Kanze escribió:
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
El Sat, 31 Oct 2009 04:41:21 -0700, James Kanze escribió:
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 ?
El Sat, 31 Oct 2009 04:41:21 -0700, James Kanze escribió:
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
On Sat, 31 Oct 2009 04:41:21 -0700 (PDT), James Kanze :
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.
On Sat, 31 Oct 2009 04:41:21 -0700 (PDT), James Kanze
<james.kanze@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.
On Sat, 31 Oct 2009 04:41:21 -0700 (PDT), James Kanze :
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.
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
On Oct 31, 3:39 pm, qdii wrote:
El Sat, 31 Oct 2009 04:41:21 -0700, James Kanze escribió:
> 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 ?
Ç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
On Oct 31, 3:39 pm, qdii <q...@reblochon.be> wrote:
El Sat, 31 Oct 2009 04:41:21 -0700, James Kanze escribió:
> 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 ?
Ç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).
El Sat, 31 Oct 2009 04:41:21 -0700, James Kanze escribió:
> 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 ?
Ç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).
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
On Nov 1, 8:34 am, qdii <q...@reblochon.be> wrote:
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.
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
James Kanze writes:
On Nov 1, 8:34 am, qdii 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
James Kanze <james.kanze@gmail.com> writes:
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
On Nov 1, 8:34 am, qdii 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
