RE: [boost] Re: Threads docs updated in CVS

From: Asger Alstrup Nielsen (alstrup_at_[hidden])
Date: 2001-08-10 04:52:53

> > > Calling join() multiple times on this object is valid... 
> > > any call made after the first simply exits immediately 
> > > since all the cleanup has already 
> > > been handled during the first call.
> > 
> > I think you should add this surprise to the documentation of join. 
> 
> This is the behavior of even the Win32 WaitFor*() methods when 
> applied to a thread.  So it shouldn't be much of a surprise.

Well, that does not change the fact that it was a surprise to me and the
fellow programmers I have asked around here.

This is a very low level thing that will not happen to most programmers,
because the situation is not common. Also, it's not properly documented
in neither the Win32 nor .NET API documentation I have here (MSDN July).
So I don't think that you can expect that a general thread programmer,
even with a background in the Java, Win32 or Posix API will know this
detail.

Why not help them?

How you want to fix this problem is up to you:

1) You can explicitly document that you expect people to have detailed
knowledge about joins and other technical terms in order for them to
understand the library sufficiently.

2) You try to help the programmer and document identified surprises.

3) You change the API so that surprises don't happen.

I can't decide which option you prefer, but respectfully, I think it
would be a mistake to sweep the issue under the carpet, especially since
this issue is contentious.

Please observe that this issue is not about changing the name or not.
That's a judgement call that only you get to make. It's about raising
the level of the documentation to document things that have been
identified as relevant issues.

Thank you,

Asger Alstrup Nielsen