[tarantool-patches] Re: [PATCH v2 4/4] Extract 'coll' library from 'core'

[Vladislav Shpilevoy <v.shpilevoy@tarantool.org>]

On 26/02/2019 16:17, Konstantin Osipov wrote:
> * Vladislav Shpilevoy <v.shpilevoy@tarantool.org> [19/02/26 16:12]:
>> Usually we either do not write readme at all, or write it in
>> the main header, describing the main functionality. And it is
>> never about build details, dependencies, and limitations.
>>
>> All limitations are usually described with corresponding enum
>> values and function comments.
> 
> I'd say it's mostly sloppiness:
> 
> kostja@chai ~/work/tarantool/src/lib
>   % ls */README*
> msgpuck/README.md  salad/README  small/README.md

msgpuck and small are separate repositories, with their
own rules. Msgpuck is even a separate project, not just
repo.

And even here you can see, that small README does not
speak about build and dependencies. It just speaks the
same, what should be written as function comments. What,
in fact, would be much more useful.

Talking of salad - it is ridiculous, howling shame, and
profanation. Just open that useless 'readme' and you will
see, that it consists of one single line:

	"salad - Some ALgorithms And Data structures"

That. Is. All. Readme just for readme.

You can name my opinion whatever you want - sloppiness, or
anything else, showing me that trumpery composed of empty
or not existing READMEs, but the fact is that we really
never write them, unfortunately, as a obligatory practice.

As an opposite to your 'readme's above I can show you
much more not described libs:

- small/rlist (part of small, by the way, but not described
   in small/README);
- small/lf_fifo (the same)
- small/rb (the same)
- all the salad/* libs (I do not count empty README as a readme)
- lib/bit
- lib/uri
- src/curl
- src/histogram
- src/httpc
- src/rmean
...
I can continue longer, but do not see any sense in it.

Libs, having their readme inside the header, as a special paragraph
or as a part of main struct comment:
- lsregion
- quota_lessor
- json
- lib/bit
- lib/bitset
- lib/coll (yes, touched in this patchset, and it has
   a description of struct coll and functions in the header)

> 
> 
> -- 
> Konstantin Osipov, Moscow, Russia, +7 903 626 22 32
> http://tarantool.io - www.twitter.com/kostja_osipov
>