On 3/19/2011 4:35 PM, Andrei Alexandrescu wrote:
On 03/19/2011 12:16 PM, dsimcha wrote:
On 3/19/2011 12:03 PM, Andrei Alexandrescu wrote:
On 03/19/2011 02:32 AM, dsimcha wrote:
Ok, thanks again for clarifying **how** the docs could be improved.
I've
implemented the suggestions and generally given the docs a good reading
over and clean up. The new docs are at:
http://cis.jhu.edu/~dsimcha/d/phobos/std_parallelism.html
* Still no synopsis example that illustrates in a catchy way the most
attractive artifacts.
I don't see what I could put here that isn't totally redundant with the
rest of the documentation. Anything I could think of would basically
just involve concatentating all the examples. Furthermore, none of the
other Phobos modules have this, so I don't know what one should look
like.
I'm thinking along the lines of:
http://www.digitalmars.com/d/2.0/phobos/std_exception.html
A nice synopsis would be the pi computation. Just move that up to the
synopsis. It's simple, clean, and easy to relate to. Generally, you'd
put here not all details but the stuff you think would make it easiest
for people to get into your library.
In general I feel like std.parallelism is being held to a
ridiculously high standard that none of the other Phobos modules
currently meet.
I agree, but that goes without saying. This is not a double standard;
it's a simple means to improve quality of Phobos overall. Clearly
certain modules that are already in Phobos would not make it if proposed
today. And that's a good thing! Comparing our current ambitions to the
quality of the average Phobos module would not help us.
Generally it seems you have grown already tired of the exchange and it
would take only a few more exchanges for you to say, "you know what,
either let's get it over it or forget about it."
Please consider for a minute how this is the wrong tone and attitude to
be having on several levels. This is not a debate and not the place to
get defensive. Your role in the discussion is not symmetric with the
others' and at best you'd use the review as an opportunity to improve
your design, not stick heels in the ground to defend its current
incarnation (within reason). Your potential customers are attempting to
help you by asking questions (some of which no doubt are silly) and by
making suggestions (some of which, again, are ill-founded).
Nevertheless, we _are_ your potential customers and in a way the
customer is always right. Your art is to steer customers from what they
think they want to what you know they need - because you're the expert!
- and to improve design, nomenclature, and implementation to the extent
that would help them.
Furthermore, you should expect that the review process will prompt
changes. My perception is that you consider the submission more or less
final modulo possibly a few minor nits. You shouldn't. I'm convinced you
know much more about SMP than most or all others in this group, but in
no way that means your design has reached perfection and is beyond
improvement even from a non-expert.
I know you'd have no problem finding the right voice in this discussion
if you only frame it in the right light. Again, people are trying to
help (however awkwardly) and in no way is that ridiculous.
Fair enough. Now that I think of it most of my frustration is that
these details are only getting looked at now, when I have a week (and an
otherwise very busy week) to fix all this stuff, when this module has
been officially in review for the past two weeks and unofficially for
several months. I would be much more open to this process if the issues
raised could be fixed at my leisure rather than on a hard and tight
deadline. This is exacerbated by the fact that I have another
important, unrelated deadline, also next Friday.
At the same time, though, I'm afraid that if we didn't fix a vote date
and put some urgency into things, the pace of the reviews would be
glacial at best, like it was for the first two weeks of official review
and the months of unofficial review.
How about we make next Friday a soft deadline/start of voting? It can
be extended as necessary by mutual agreement of me and Lars (the review
manager), and likely will be if the review process is still yielding
good suggestions and/or I haven't had time to implement/clean up some
key things. Having a deadline breathing down your neck like this is
really not conducive to being open to suggestions and thoughtful
consideration, especially for issues that seem like fairly minor details.
Also increasing the deadline pressure issue, Michael Fortin just caused
me to rethink the issue of exception handling in parallel foreach. I
had more-or-less working code for this, but I realized it's severely
broken in subtle ways that I've (knock on wood) never actually run into
in real world code. It's gonna take some time to fix. These kinds of
issues with error handling code can very easily slip under the radar in
a library with only a few users, and unfortunately, one has. I
definitely know how to fix it, but I have to implement the fix and it's
somewhat non-trivial, i.e. I'm debugging it now and it's looking like a
marathon debugging session.
