Discussion :

[Garulfo]

salut,

j'utilise ocamldoc pour documenter mon code -_-

Mauvaise surprise : il y a des sauts de lignes régulièrement après chaque "->" ou presque dans les typages.

De plus j'ai des lignes blanches qui apparaissent dans les info sur les modules -_-

Peut-on configurer plus que ce qu'il y a écrit dans le manuel (man ocamldoc)? Je veux dire en dehors de recréer un générateur (15.3.1)... juste avec des options. J'aimerais particulier supprimer les sauts de ligne et obtenir que TOUT la longueur de l'écran soit utilisé.

Et comment font-ils pour obtenir leur doc sur le site d'ocaml ?
Je n'ai pas trouvé les sources commentés.

Je joins deux images pour illustrer ^_^ Merci

[gasche]

Il est possible d'avoir accès aussi au code qui a donné lieu à ces images ?

[Garulfo]

Oui mais tu risque d'être déçu... c'est très straigh

Celui-ci est pour la première image

Code ocaml :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
 
module Process_set = Set.Make( struct type t=name
                                      let compare = compare
                               end
                               )

Celui-ci est pour la deuxième image

Code ocaml :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
 
let qchoice var constant_set proc = Qchoice (var, constant_set, proc)
 
let synchro label_set ~left ~right = Synchro (label_set, left, right)
 
let qsynchro label_set var constant_set proc = Qsynchro (label_set, var, constant_set, proc)
 
let guard predicate_name terms proc = Guard ((predicate_name, terms), proc)

Comme tu vois... rien de spécial. Voici le code HTML généré pour qsynchro

Code html :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
 
<span class="keyword">val</span> <a name="VALsynchro"></a><a href="code_VALEbs_process.synchro.html">synchro</a> : <code class="type"><a href="Ebs_label.html#TYPEset">Ebs_label.set</a> lazy_t -&gt;<br>       left:<a href="Ebs_process.html#TYPEexpression">expression</a> -&gt;<br>       right:<a href="Ebs_process.html#TYPEexpression">expression</a> -&gt; <a href="Ebs_process.html#TYPEexpression">expression</a>

On voit apparaître les <br> après les -&gt; ...
Je te dirais que, à priori, c'est un problème de longueur, mais ce n'est pas aussi évident. Sur une expression il coupe alors qu'elle serait plus petite qu'une qu'il a laissé en entier.

---

La coupure après les "->" des typages est ce qui me fatigue le plus. Ça n'arrive pas tout le temps. Par exemple les deux définitions ci-après ne le font pas

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
 
let action label parameters = Action (label, parameters)
 
let process_call name parameters = ProcessCall (name, parameters)

Est-ce que ça ne le fait à personnes d'autres ?

[InOCamlWeTrust]

Une liste complète, et que je trouve assez ahurissante, des possibilités de ocamldoc se retrouvent sur le manuel de référence.

http://caml.inria.fr/pub/docs/manual...manual029.html

Tu verras entre autres dans les paragraphes 15.3 et 15.4 comment customiser son ocamldoc. Pour celà, il faut avoir ocamldoc compilé en version byte-code, à cause du chargement dynamique de code, justement, sinon, ça marche pas. En général, à moins que ça ait changé, les distribution binaires disponibles sur la page de Caml N'INCLUENT PAS ocamldoc en byte-code, mais seulement en natif.

Bonne lecture !

P.S. : les man Caml sont archi-mal faites et ne sont pas à jour.

[gasche]

Bon, j'avais jamais tripoté ocamldoc avant donc j'ai décidé que ça pourrait être amusant de résoudre ton problème.

Attention, c'est un "hack" : la solution n'est pas conceptuellement jolie, et ça marche même pas trop bien. Mais ça marche.

J'utilise un custom generator à ma sauce : en gros je prends le générateur html normal, mais je court-circuite son output des types pour virer les sauts de ligne inutiles.

Le code source (virer le ".html" pour avoir le .ml)

Voilà ma commande de compilation :

ocamlc -I $(dirname `ocamldoc -customdir`) -c mygen.ml

Commande d'utilisation :

ocamldoc doc.mli -g mygen.cmo -max-line-length 200

Tu peux jouer sur l'argument max-line-length. La valeur par défaut est 80 mais vu la façon dont la fonction de base met les \n, ça ne marche pas toujours très bien.


Edit : C'est un hack parce que ça ne règle pas le problème à sa source : en particulier, à priori tous les autres générateurs souffriront aussi du problème des sauts de lignes intempestifs, puisqu'il n'est pas spécifique à la sortie HTML (ça vient de plus haut). J'ai cherché plus haut dans le code, n'ai rien vu qui soit clairement la cause du problème, et en plus ce sont des endroits non-modifiables parce qu'appartenant au coeur du code du compilo (il faudrait patcher la distrib entière pour y faire des modifs, la poisse). Le hack laid me paraît la méthode la plus efficace de régler le non-problème initial.

Par ailleurs, il est d'usage d'utiliser ocamldoc plutôt sur les .mli que les .ml (même si ça marche aussi, mais je pense que le premier problème est du à ça : il ne gère pas les (struct ... end) baroques en plein milieu du code, puisque les interfaces n'ont jamais ce genre de trucs).

[Garulfo]

Bon, j'avais jamais tripoté ocamldoc avant donc j'ai décidé que ça pourrait être amusant de résoudre ton problème.

Attention, c'est un "hack" : la solution n'est pas conceptuellement jolie, et ça marche même pas trop bien. Mais ça marche.[...]
Edit : C'est un hack parce que ça ne règle pas le problème à sa source : en particulier, à priori tous les autres générateurs souffriront aussi du problème des sauts de lignes intempestifs, puisqu'il n'est pas spécifique à la sortie HTML (ça vient de plus haut). J'ai cherché plus haut dans le code, n'ai rien vu qui soit clairement la cause du problème, et en plus ce sont des endroits non-modifiables parce qu'appartenant au coeur du code du compilo (il faudrait patcher la distrib entière pour y faire des modifs, la poisse). Le hack laid me paraît la méthode la plus efficace de régler le non-problème initial.

Par ailleurs, il est d'usage d'utiliser ocamldoc plutôt sur les .mli que les .ml (même si ça marche aussi, mais je pense que le premier problème est du à ça : il ne gère pas les (struct ... end) baroques en plein milieu du code, puisque les interfaces n'ont jamais ce genre de trucs).

C'est hallucinant qu'il ait mis ça au cœur du compilateur... Dans ce cas comment génère-t-il leurs propre doc ? Hackent-t-ils aussi ?

En tout cas : merci beaucoup... Je vais essayé ta solution. Il n'y a donc que la solution de refaire un générateur... Va falloir que je regarde ça de plus prés.

sinon j'ai essayé avec les .mli mais ça ne résoud pas le saut de ligne... certes ça ne met plus les (struct ... end)

[Garulfo]

Une liste complète, et que je trouve assez ahurissante, des possibilités de ocamldoc se retrouvent sur le manuel de référence.

http://caml.inria.fr/pub/docs/manual...manual029.html

J'avais déjà tout lu ça -_-
De fond en comble.
Il n'y a aucune option pour régler la longueur d'une ligne par exemple.

La seule que je vois c'est de refaire un générateur. Mais juste pour éviter un saut de ligne je trouve ça débile.