LouisCharlesC / safe

Header only read/write wrapper to combine mutexes with locks.
MIT License
149 stars 11 forks source link

Some comment and changed on the readme #3

Closed TaoDominique closed 5 years ago

TaoDominique commented 5 years ago

Hello,Magnifique travail, tellemen rien à dire que j'ai juste fait qqn reformatage, je trouve personnellement plus lisible quand le texte est un peu plus aéré, surtout au début ^^' ... Et quelques corrections et suggestions comme si bien indiqué ci-après:

Dans ton premier exemple "With Safe": le commentaire // access the value using pointer semantics: and ->, même si ca semble bien sur logique, ne serait ce pas une bonne idée de préciser que tu redéfinis les opérateurs et -> dans ta classe pour éviter toute confusion au début, vu que c'est le premier code qui plonge le lecteur dans ton code ?

Personnellement, me suis un peu cassé la tête à analyser les exemples de la section "Main Features", en tant que lecteur, et surtout parce que la section "basic usage" est assez courte, j'aurais préféré pouvoir lire le basic usage en premier avant d'aller plus profondément dans les avantages et la manière d'utiliser plus "subtilement l'interface" avec la section Main features: Mon ordre de section: Overview, basic usage, main features, going a little deeper et advanced usages Enfin je dis ca, c'est surtout parce que j'aime bien savoir un minimum ce que fait l'interface safe et comment grossomerdo faire appelle pour construire un objet avant de dig deeper dans ce qu'il permet de faire

Un autre commentaire dans la meme direction de l'ordre des sections: ne serait ce pas judicieux d'eclaircir le lecteur avide de savoir sur l'agencement du readme ? Genre, " Firstly, the basic usages of the safe interface is explained in the first section. The following section goes a little bit deeper on the possibility of this library, also serving as a transition to enlighten the reader on main advantages of this library which constitutes the wholes content of section 3. ...etc ou un truc comme ca quoi ^^'

Dans basic usage, est ce pas bien de mettre safe::Safe<int, std::mutex> value; , juste pour montrer l'equivalence avec safe::Safe value; et montrer déjà la possibilité d'une construction flexible ? Parce que dans la section main features, tu parles de flexibilité avec différent cas d'exemple, perso avoir juste un exemple avant pour illustrer sans vraiment expliquer (dans le basic usage) puis ensuite de voir cette formidable possibilité de flexibilité permet au lecteur de se dire "Wouhaahaha", genre un petit fil conducteur quoi =)

A et perso, je trouve pas mal d'avoir une petite liste des fonctions membres qu'on peut appelé mais bon les exemples je les ai trouvé clair donc tout bon (par example, on comprends comment construire l'object safe, que Access est aufet une autre class qui s'allie bien avec la class safe ...etc). J'ai juste eu une confusion avec la class Access et la méthode access mais rien de bien méchant aufet

LouisCharlesC commented 5 years ago

Wah, merci Dominique. Je regarde ça aussitôt que j'ai le temps!

LouisCharlesC commented 5 years ago

Bon, j'arrête. Dis-moi ce que tu en penses. J'ai fait à peu près la moitié des modifs suggérées.

TaoDominique commented 5 years ago

Hello, j'ai fait une relecture rapide dans la preview du README. Ca me va, ca m'a l'air plus cool. Si je relis, j'ouvrirais une autre branche et une autre PR. Normalement tu devrais pouvoir merger cette PR dans master