Utilisation et configuration de ocamldoc

**Garulfo** · 20/06/2008, 02h28

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** · 20/06/2008, 07h12

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

**Garulfo** · 20/06/2008, 09h14

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 -> ...
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** · 20/06/2008, 14h58

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** · 20/06/2008, 16h16

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** · 20/06/2008, 19h07

Envoyé par 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

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.

**Garulfo** · 20/06/2008, 19h13

Envoyé par bluestorm

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)

**gasche** · 20/06/2008, 19h37

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 ?

Euh il faut pas exagérer, "au coeur" ça veut juste dire que la fonction qui produit une string à partir d'un type (qui est utilisée par de nombreux front-end : toplevel, ocamldoc...) se trouve dans typing/ . Ça n'a rien d'un hack immonde et ce n'est pas spécialement déraisonnable.

Il n'y a donc que la solution de refaire un générateur...

Encore une fois, pas de quoi s'offusquer. "Refaire un générateur" ça veut juste dire reprendre un générateur existant et surcharger le comportement (c'est pas comme si on recodait tout, hein). Ça n'a rien de monstrueux, et pour ce qu'on veut faire c'est même très efficace (syntaxiquement, conceptuellement, etc.).

**Garulfo** · 20/06/2008, 20h42

Envoyé par bluestorm

[..]
Encore une fois, pas de quoi s'offusquer. "Refaire un générateur" ça veut juste dire reprendre un générateur existant et surcharger le comportement (c'est pas comme si on recodait tout, hein). Ça n'a rien de monstrueux, et pour ce qu'on veut faire c'est même très efficace (syntaxiquement, conceptuellement, etc.).

certes... et je n'en disais pas plus... Mais c'est le genre d'option qu'on s'attendrait à voir dans une commande en ligne
ocamldoc --endline=120
par exemple

Mais tu n'as pas répondu à mon autre question. Sais-tu comment ils génèrent leur doc (sur le site i mean)?

**Garulfo** · 20/06/2008, 20h57

Humm ta solution n'a pas fonctionnée chez moi.
Je vais réessayer...

**Garulfo** · 20/06/2008, 22h46

Bon en ajoutant des printf dans chaque clause, je vois qu'il n'y a rien qui s'affiche... je suppose que ce n'est pas normal

Je pense que de toute façon ce n'est pas juste la longueur...
du moins, pas la longueur du texte, mais éventuellement la longueur du code.

Regardes l'image qui suit.

Bon je laisse faire, j'ai d'autre chose plus importante.

Mais je me demande quand même : est-ce que je suis le seul à avoir ce genre de chose ici ? ou peut-être n'utilisez-vous jamais ocamldoc ?

**InOCamlWeTrust** · 20/06/2008, 22h50

Moi, jamais. J'ai juste essayé une fois un peu sérieusement, et j'ai trouvé ça trop bien mais trop chiant ! comme Camlp4, en fait...

**gasche** · 20/06/2008, 22h53

Bon en ajoutant des printf dans chaque clause, je vois qu'il n'y a rien qui s'affiche... je suppose que ce n'est pas normal

Comment est-ce que tu compiles puis exécute ?

**Garulfo** · 20/06/2008, 23h19

Envoyé par bluestorm

Comment est-ce que tu compiles puis exécute ?

Avec les deux commandes que tu m'as donné :

Code :

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

1
2
3
4
5
6
 
ocamlc -I $(dirname `ocamldoc -customdir`) -c gen_ocamlpai.ml 
 
ocamldoc -v -html -css-style style.css -colorize-code \
             -g gen_ocamlpai.cmo -max-line-length 800 \
             -t OCamlPAI -d doc/ *.ml

Voici la sortie produite par l'option -v

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
Analysing file ebs_constant.ml...
Ok
Analysing file ebs_dependency_formula.ml...
Ok
Analysing file ebs_environment.ml...
Ok
Analysing file ebs_label.ml...
Ok
Analysing file ebs_lexer_rules.ml...
Ok
Analysing file ebs_pai.ml...
Ok
Analysing file ebs_parser.ml...
Ok
Analysing file ebs_parser_rules.ml...
Ok
Analysing file ebs_predicate.ml...
Ok
Analysing file ebs_predicate_definitions.ml...
Ok
Analysing file ebs_prettyprinter.ml...
Ok
Analysing file ebs_printer.ml...
Ok
Analysing file ebs_process.ml...
Ok
Analysing file ebs_reduction.ml...
Ok
Analysing file ebs_term.ml...
Ok
Analysing file ebs_variable.ml...
Ok
Merging...
Ok
Cross referencing...
Warning: Module or module type Hashtbl.Make not found
Warning: Module or module type Set.Make not found
Warning: Module or module type Set.Make not found
Warning: Module or module type Set.Make not found
Warning: Module or module type Hashtbl.Make not found
Warning: Module or module type Set.Make not found
Warning: Module or module type Set.Make not found
Warning: Module or module type Set.Make not found
Ok
Generating documentation...
Generate for module Ebs_constant
Generate for module Ebs_constant.Constant_set
Generate for module Ebs_dependency_formula
Generate for module Ebs_environment
Generate for module Ebs_label
Generate for module Ebs_label.Label_set
Generate for module Ebs_lexer_rules
Generate for module Ebs_pai
Generate for module Ebs_parser
Generate for module Ebs_parser_rules
Generate for module Ebs_predicate
Generate for module Ebs_predicate_definitions
Generate for module Ebs_prettyprinter
Generate for module Ebs_printer
Generate for module Ebs_process
Generate for module Ebs_process.Process_set
Generate for module Ebs_process.Table
Generate for module Ebs_reduction
Generate for module Ebs_term
Generate for module Ebs_variable
Ok

J'ai rajouté des printf dans chacune des clauses de ton if dans rewrap et je ne vois rien apparaître.

Comme je t'ai dis ce n'est pas primordial. Je ne t'en voudrais donc pas de ne pas te casser la tête pour ça

C'est sympa d'avoir déjà cherché.

**gorgonite** · 20/06/2008, 23h28

franchement, comme souvent OCaml, le projet est bon, tout fonctionne assez bien... mais rien n'est réellement utilisable en "boite noire"

pour infos, F# génère de super-docs très facilement

**Garulfo** · 20/06/2008, 23h40

Envoyé par gorgonite

[...]
pour infos, F# génère de super-docs très facilement

Toi aussi tu t'y mets

**gorgonite** · 20/06/2008, 23h42

Envoyé par Garulfo

Toi aussi tu t'y mets

ben j'ai switché... et peu de choses me manquent (les foncteurs, l'inférence de type sur les objets)

alex_pi · 21/06/2008, 10h11

Envoyé par gorgonite

ben j'ai switché...

Traitre !! Abandonner comme ça ce bô langage Français Môssieur, c'est une honte !

**Jedai** · 21/06/2008, 13h09

De mon côté je trouve la communauté Haskell plus intéressante et le langage est tellement "pur fonctionnel" qu'il te force à adopter une perspective bien différente sur beaucoup de problèmes, je trouve ça plus stimulant, et parfois tu découvres des techniques très impressionnantes.

A noter que Haddock produit des résultats plus jolis et plus complets qu'ocamldoc à mon goût.

--
Jedaï