Re: [MTASCsft PATCH WIP5 00/33] MT-, AS- and AC-Safety docs

["Carlos O'Donell" <carlos at redhat dot com>]

On 11/13/2013 03:11 AM, Alexandre Oliva wrote:
> Here's an updated version of the patch series that documents
> Multi-Thread, Async Signal and Async Cancel safety properties of our
> implementation.
> 
> A few files with functions containing lots of dependencies were
> completed since the last round.  I modified the commit messages so
> that stgit would indicate the files in the subject of each patch
> email.  I think I have clearer definitions for
> uunguard/xguargs/staticbuf, but I'm yet to complete reviewing all uses
> thereof.  The new marks are tempsig, stimer, and uplugin.
> 
> 
> Here's a summary of of the number of @deftypefu?n entries in each file
> in the manual, how many @safety notes there are, how complete the
> safety documentation for that file is, and how many other functions
> I've (so far) noticed as not documented at all in the manual, but that
> should be documented in that file (with a @safety note to go with it)
> 
>             Filename @def @saf  cmplt% undoc
>    manual/stdio.texi  126  126 100.00%   0                                      
>    manual/arith.texi  102  102 100.00%   0
>   manual/string.texi   99   99 100.00%   1
>     manual/math.texi   86   86 100.00%   0
>  manual/filesys.texi   78   78 100.00%  18
>     manual/llio.texi   53   53 100.00%   1
>   manual/memory.texi   44   44 100.00%   0
>    manual/ctype.texi   36   36 100.00%   0
>  manual/process.texi   22   22 100.00%   0
>  manual/charset.texi   18   18 100.00%   0
>    manual/errno.texi   13   13 100.00%   0
>  manual/message.texi   12   12 100.00%   0
>      manual/job.texi   11   11 100.00%   0
>  manual/pattern.texi   11   11 100.00%   0
>    manual/crypt.texi   10   10 100.00%   0
>     manual/lang.texi    7    7 100.00%   0
>     manual/argp.texi    6    6 100.00%   0
>   manual/locale.texi    5    5 100.00%   0
>     manual/conf.texi    4    4 100.00%   0
>    manual/debug.texi    3    3 100.00%   0
>   manual/getopt.texi    3    3 100.00%   0
> ----
>   manual/search.texi   15    7  46.67%   0
>   manual/signal.texi   27    7  25.93%   0
> manual/resource.texi   31    7  22.58%   0
> manual/terminal.texi   24    5  20.83%   0
>  manual/startup.texi   15    3  20.00%   0
>    manual/users.texi   66   11  16.67%   0
>     manual/time.texi   33    5  15.15%   0
>   manual/socket.texi   59    5   8.47%   0
>  manual/sysinfo.texi   22    1   4.55%   0
> ----
> manual/platform.texi    8    0   0.00%   0
>   manual/setjmp.texi    8    0   0.00%   0
>   manual/syslog.texi    5    0   0.00%   0
>     manual/pipe.texi    4    0   0.00%   0
>  manual/threads.texi    2    0   0.00% 119
>    manual/libdl.texi    0    0   0.00%   9
> ----
>                Total 1068  800  74.91% 148

These statistics give me goosebumps, I love seeing documenting
get an update like this. We've already found this review userful
internally at Red Hat to answer customer questions, so I'm excited
to see it get checked in.

Overall there have been no objections to these annotations except
those posed by Torvald Riegel and Rich Felker surrounding the
value of the documentation given that MT-safe is a weakened definition
based on the loose language in the POSIX standard meaning data-race
free. The resolution here has been that Torvald and others are going
to work upstream to make sure that we get more precise language into
the standard. I'll be helping with that. It isn't something you need
to worry about unless you are also interested in helping out on that
front in the future. I imagine though that after this review you might
not want to see any documentation work for a while :-)

The only other objection we've had is from Joseph Myers who would
prefer you fix the bugs instead of documenting them. I agree that fixing
bugs is good but that's orthogonal to your purpose with this work and
would impact completing it on time. I'm happy to come back and do bug
fixing after we get this done.

Without any solid objections from anyone, I'm going to do my review
of your patches one-by-one and give you my ACK for these changes.

If you agree, and I agree, and nobody else (Joseph, Torvald, or
Rich) disagrees, we can start checking in these notes for 2.19.

I'm going to explicitly ask Joseph, Torvald, and Rich to comment
again on their approval for this project.

Cheers,
Carlos.