On Sunday 15 July 2007 23:44, Danny Smith wrote:
> Documentation? What's that?
The last 20% of the job, that most of us, as programmers, tend to put
off till a rainy day. Five years later, when we still haven't done it
and need to revisit the code, we kick ourselves because the minimal
comments we added in-line, or in the headers, just weren't quite good
enough; `been there, done that, got the tee-shirt'.
> I think best (minimal) place is in the headers itself.
With respect, Danny, I disagree. Brian Dessent persistently tells us
that the definitive reference is MSDN. That's fine for all of the
Microsoft standard stuff, but completely useless for any extended
behaviour we've added. I believe that we need a centralised point of
reference, for MinGW extensions; trawling the headers for randomly
scattered comments is the last place I want to have to look for that,
especially when I don't know what I'm looking for, in the first place.
My ideal would be `man mingwex', giving a summary of what extensions are
available, with pointers to any more detailed documentation, which may
be available. Yes, that needs a bit of committment, to maintain it,
but, `if a job is worth doing, it's worth doing it properly'.