[containers-users] Commentaires Containers - questions diverses

[JP R]

D'abord merci pour l'acceptation rapide de mes 2/3 derniers PRs
(@Fourchaux). C'est sympa.

J'ai pris des notes durant l'écriture de ces PRs et je me permets de t'en
envoyer quelques-unes pour avoir ton avis, éventuellement (c'est tout en
vrac, sorry).

(Les commentaires viennent surtout de Batteries et JST_Base).

Le répertoire src/core est principalement concerné.

* Noms de modules: écrits en camlCase sauf CCArray_slice.

* CCArray.to_seq:
Correspond à (Base.Array_ to_sequence :) 'the input array is copied
internally so that future modifications of it do not change the sequence. '

ou à (Base.Array_to_sequence_mutable :) 'the input array is shared with the
sequence and modifications of it will result in modification of the
sequence.' ?

* CCHashtbl.S.keys_list & CCHashtbl.Poly.keys_list :
Rajout de: 'If the key is in the Hashtable multiple times, all occurrences
will be returned' ?

* CCHeap.S :
Les fonctions of_seq, of_klist, of_gen & to_seq, to_klist, to_gen
sont-elles de Complexity: O(n log n) ?

* CCList.of_seq / of_gen / of_klist :
Rajout de: 'In the result, elements appear in the same order as they did in
the source sequence/gen/klist.' ?

* CCList.mli :
(** {2 Lists of pairs} *) : dernière ligne à supprimer ?

* CCList.foldi & CCListlabels.foldi :
Fonctions Tail-recursive ?

* CCOpt.exists & CCOpt.for_all:
Rajout de : 'This is a short-circuiting operation' ?

* CCVector.of_array:
Rajout de: 'Operates in O(n) time.' ?


De manière plus générale :

* Est-il nécessaire de garder les (très laides lignes !) Since: dans la doc
finale ?
Il serait bien d'avoir une première page avec les seules infos de base
(noms fonctions + types + descriptions) et une autre page avec des infos
diverses (versions, exemples d'utilisation, sources ...) comme dans les
docs de F#, Rust, etc... etc...
Mais bon, c'est un autre problème.

A propos, tu génères comment tes docs Containers ?
Actuellement si je lance $ make doc
j'ai des messages d'erreur du genre :

odoc: internal error, uncaught exception:
      File "src/docOckIdentEnv.ml", line 260, characters 22-28: Assertion
failed ...
Pb odoc, jbuilder, autre ????

* Des fonctions identiques ont des noms différents dans Containers,
Batteries ou Base.
Plus gênant des noms identiques correspondent à des fonctions différentes.
Base.Array.findi <> CCArray.findi <> BatArray.findi
Un peu dommage !

* Des fonctions s'appellent mapi, findi, foldi sauf CCArray.find_map_i
(pourquoi pas CCArray.find_mapi ?)

* Des fichiers *.mli (CCFormat.mli - CCList.mli - CCListLabels.mli et
surtout CCString.mli) possèdent des tests qtest.
Pas préférable de mettre tous les tests dans les fichiers *.ml ?

* Inversement on trouve des Comments identiques dans des fichiers foo.ml et
foo.mli. (Ex: CCSet.ml et CCSet.mli).
Pas mieux de réserver les commentaires aux seuls fichiers *.mli ?
Rem: dans ces cas-là je n'ai modifié que les seuls *.mli. Désolé.

* Je n'ai pas trop de commentaires pour les fonctions:

- 'add_foo'
- 'array'
- 'bool'
- 'float/3'
- 'int' & 'int32' & 'int64'
- 'nativeint'
- 'CCHash.combine/2/3/4'
- beaucoup de fonctions 'compare' et 'equal'
- 'fold_l' & 'fold_m'
- 'gen' & 'gen_cpy'
- 'klist' & 'klist_cpy'
-'list' & 'list_cpy'
- 'hash'
- 'map_m'
- 'pair'
- 'pop'
- 'push'
- 'quad'
- 'random' & 'random_foo'
- 'sequence_m'
- 'string'
- 'triple'
- 'write_lines_l'

Grrrrrr .....

* Il serait bien de développer/écrire des présentations pour chaque module.
Dans ce domaine, Batteries est plutôt bien fait, je trouve. (mais là mes
connaissances sont trop faibles pour pouvoir écrire du texte technique
pertinent).

* Rem: le module CCMonomorphic semble important. Quelqu'un (jpdeplaix ?)
écrive une présentation dans CCMonomorphic.mli.

Sinon, j'ignore tes intentions mais j'espère que tu vas continuer à
développer Containers.
Je suis curieux de voir l'influence que va avoir Base (avec l'arrivée
annoncée d'une documentation, la ré-écriture des exemples de RWO et la
propagande de JST ...) .
Je serais également curieux d'avoir l'avis des Gourous OCaml (qui refusent
presque toutes modifs de la Std librairie) à propos de Base.
En faisant 'open Base' et en tapant les tout premiers exemples de la doc
OCaml officielle on reçoit des tonnes de "Warning - deprecated" mais aussi
des erreurs sur du code très très basique (# (1 < 2) = false) . C'est quand
même chaud !

Mais bon, si c'est l'avenir.

Bien, on va stopper là.

A+

PS : lors des élections de novembre prochain tu vas être aux premières
loges pour assister au basculement politique du Texas (même si Austin est
déjà démocrate ). Le Texas. Un Blue State. MAGA !!!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ocaml.org/pipermail/containers-users/attachments/20180202/ef3c1ebc/attachment.html>