[containers-users] Commentaires Containers - questions diverses

Simon Cruanes simon.cruanes.2007 at m4x.org
Sat Feb 3 02:47:11 GMT 2018


Might have been better to redirect to my private email, sorry folks
(altough, if you speak french, there's a lot of interesting questions
and remarks in JP's email). He's contributed a lot of typographic
improvements and added documentation (patience > 9000).

You can disregard my answers otherwise, it's going to be weird out of
context.

Le Fri, 02 Feb 2018, JP R wrote:
> 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.

Consistency in style is not one of my strengths :/

> * 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.' ?

Shared (the second one). Copying would ruin the point of using a
sequence in the first place.

> * 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) ?

`of_*` probably are (just a sequence of inserts); `to_*` I'm not sure
how the amortized costs combine if we traverse the whole structure.
Might be less.

> * 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.' ?

why not.

> * 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' ?

for options that doesn't really make sense, does it?

> 
> * 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.

Yes, that's useful info and it's also available in ocp-browser.

> 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 ????

odoc I suppose. I use 4.05.0+flambda for day to day dev fyi.

> * 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 !

-> fragmentation!

> * 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 ?

These files used to be cppo files (which would not be accepted by
qtest). We can move the tests back into the .ml files now.

> * 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).

I agree. Even a few lines at the beginning explaining what the intended
use is, would be useful.

> * 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.

I do intend to continue :-)

> 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 ...) .

Base seems to have a good design but I don't want to rewrite tens of
thousands of lines of code (probably not far from 100k) just because
they decided to be incompatible with the stdlib.

> 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.

^^
who knows…

> 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 !!!

Heh, wait and see! 


-- 
Simon Cruanes

http://weusepgp.info/
key 49AA62B6, fingerprint 949F EB87 8F06 59C6 D7D3  7D8D 4AC0 1D08 49AA 62B6
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.ocaml.org/pipermail/containers-users/attachments/20180202/e1e0bc40/attachment.sig>


More information about the Containers-users mailing list