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-11-04 20:50:40

On 11/4/2016 6:44 PM, Klemens Morgenstern wrote:
> Am 04.11.2016 um 23:17 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!
>>
>> I vote to accept the Process library.
>>
>> I highly suggest that the documentation be expanded beyond the
>> tutorial to provide topics explaining all the major areas of the
>> library. I don't feel that one-liner reference comments even come
>> close to explain all the areas that the library covers. As an example
>> of this I hunted in the reference to find that the library provides
>> low-level access in its environment.hpp header to the process ID and
>> the native process handle, but even here any explanation for what else
>> is in the header, as well as its meaning, is almost non-existent. It
>> always baffles me when a developer provides useful functionality in
>> his library but does not bother to explain what that functionality
>> entails. Is it laziness ? Is it tiredness ? Is it an inability to
>> write a few coherent sentences in English because of lack of education
>> or that English is not the developer's native language ? I just don't
>> know.
> Ouch. Well I can't hide behind the language card after demonstrating
> that I'm rather able to write in english on the mailing list. The
> assumption is: if you use environment.hpp you already no what this is
> supposed to do

How does one know to use environment.hpp when

1) There is no previous documemtation that it exists
2) Even if one finds it the explanation of functionality in it is very 
terse.

In other words you, the library developer, know that there is valuable 
functionality involved there, so why would you want to bury it with 
barely no explanation instead of explaining what you yourself have 
provided ? Or, better explained, why do the work of adding useful 
functionality to your library unless you are going to tell end-users of 
your library about it ? Library development is not a "find the treasure" 
game, it's an effort to create functionality which makes programming 
easier for a particular domain.

>, since you read the OS documentation. The reason for that
> is that I was familiar with this stuff when I started to use
> boost.process 0.5. If you know that much, I think the documentation does
> suffice. But I would also be insincere if I claimed that writing
> documentation is my favorite thing in the world.
> But since this was now critized by many, I will add a chapter explaining
> all those concepts, i.e. pipes, environment, process groups and a bit of
> asio.
>>
>> On the plus side the library provides basic useful functionality for
>> what a process library should provide in a cross-platform way. I
>> especially like the idea that the library is focused on this basic
>> functionality and that the syntax for using that functionality is
>> clear and easy to use. I also like the idea that the library relies on
>> already established Boost functionality in asio for accomplishing more
>> difficult tasks rather than trying to re-invent everything or trying
>> to provide more all-purpose interfaces which nobody can understand how
>> to use.
>>
>> The library is obviously very useful whenever the task of creating and
>> communicating with child processes needs to be done.
>>
>> I tested the basic functionality with VC++14, update 3, on Windows.
>> Everything worked as expected.
>>
>> My effort was a few hours of reading documentation to understand what
>> the library entailed and a few hours to test it out. I have a great
>> deal of knowledge involving processes on Windows and only a small
>> amount of knowledge involving processes on Linux.