Re: [boost] [process] Formal Review starts today, 27 October

Subject: Re: [boost] [process] Formal Review starts today, 27 October
From: Edward Diener (eldiener_at_[hidden])
Date: 2016-10-31 12:11:36

On 10/31/2016 10:59 AM, Klemens Morgenstern wrote:
> Am 31.10.2016 um 15:27 schrieb Edward Diener:
>> On 10/27/2016 2:26 AM, Antony Polukhin wrote:
>>> Dear Boost community,
>>>
>>> The formal review of Klemens David Morgenstern's Process library
>>> begins today, 27th October and ends on 5th November.
>>>
>>>  Process is a C++11 library to manage system processes. It can be
>>> used to:
>>> * create child processes
>>> * setup streams for child processes
>>> * communicate with child processes through streams (synchronously or
>>> asynchronously)
>>> * wait for processes to exit (synchronously or asynchronously)
>>> * terminate processes
>>>
>>> Full documentation with examples and tutorial is available at
>>> http://klemens-morgenstern.github.io/process/index.html
>>> Stable source codes for review are available at
>>> https://github.com/klemens-morgenstern/boost-process/tree/boost_review
>>> Latest source codes available at
>>> https://github.com/klemens-morgenstern/boost-process
>>>
>>>
>>> We encourage your participation in this review. At a minimum, kindly
>>> state:
>>> - Whether you believe the library should be accepted into Boost
>>>   * Conditions for acceptance
>>> - Your knowledge of the problem domain
>>>
>>> You are strongly encouraged to also provide additional information:
>>> - What is your evaluation of the library's:
>>>   * Design
>>>   * Implementation
>>>   * Documentation
>>>   * Tests
>>>   * Usefulness
>>> - Did you attempt to use the library? If so:
>>>   * Which compiler(s)
>>>   * What was the experience? Any problems?
>>> - How much effort did you put into your evaluation of the review?
>>>
>>>
>>> We await your feedback!
>>>
>>
>> This is just an initial review of the process library.
>>
>> I am looking at the documentation but I have not tried anything yet. I
>> like the focus of the library. The tutorial is good but since some
>> areas are pretty terse I was expecting a further explanation of some
>> of the concepts in the library. But a further explanation does not
>> exist. I am expected to understand how to use the library from the
>> tutorial and reference. I think a discussion of using pipes, no matter
>> how small it might be, for input and output should be part of the
>> documentation. Similarly groups are mentioned in the tutorial without
>> explaining their purpose at all.
> I guess a small section called "concepts" which explains the basics of
> what a pipe etc. is, and links to more detailed explanations, wouldn't
> hurt. It seems not everyone is hacking everything into google.

If you create your own library I do not think that Google is what you 
should be expecting people to use to understand your concepts and their 
functionality. That's why you write docs, so people understand what you 
are offering. If what you are offering is essentially the same syntax 
and functionality as something else which already exists and is 
explained adequately somewhere else then a link to that explanation 
should eb sufficient.

>>
>> I found the notation for the std_out, std_err, and std_in to be
>> exactly the opposite of what I would expect. I would think std_out and
>> std_err would use a '<' notation and std_in would use a '>' notation.
>> But using the pipes was fairly straightforward. I found the naming in
>> the tutorial a bit strange, where a bp::opstream is called 'in' and a
>> bp::ipstream is called 'out'.
> That's the nature of the problem: output of the child is input for the
> father. Hence std_out is redirectin the stdout of the child into a
> ipstream, which is called out, because it's the output of the child
> proces.  Strange, but actually makes sense.

I understand what you are saying. Naming variables in your tutorial is a 
your choice and has nothing to do with your library syntax. Still you 
might want to reconsider the std_out, std_err, std_in operator syntax 
since I think it runs contrary to what most would expect. But it is a 
really minor issue.

I am much more intersted that you adequately explain all areas of 
functionality in your library, even briefly, rather than relying on 
people to discover them in the reference. For me personally the 
reference in documentation is just a syntactical document of 
functionality and a library author should not expect an end-user to dig 
into the reference to discover what a library has to offer.

>>
>> In general I think the library is focused and very promnising. But I
>> would still want something between the tutorial and the reference
>> discussing all the main concepts of the library, so that the end-user
>> does not have to dig in the reference to understand what areas of
>> functionaity the library has to offer.