Re: [fetchmail-devel] An actual patch

[Matthias A. <mat...@gm...>]

Am 24.05.2010, 21:30 Uhr, schrieb Rainer Weikusat:

> 	- I've tried to document everything not completely trivial in
>           form of comments in the uid_db.c file. IMO, this is a mixed
>           blessing because an algorithm is not necessarily easier to
>           understand when described in natural language and everybody
>           contemplating to do something with code needs to understand
>           that, anyway ...

For me, the usual policy is saying in comments what can't be better  
written as code, so for descriptions of algorithms, it is just a  
documentation of the interface; internal commentary is just a sketch and a  
terse high-level summary, and not a duplication of what the code is  
saying. Examples: lock.?, xmalloc.?

I will want to reformat this so that Doxygen can parse it, but I'll hold  
off on that until I get a "final" version of your patch so that we're not  
stepping on our toes.

In particular, /** ... */ is special for Doxygen and marks the comment as  
a documentation comment that precedes the code (for instance, a function  
or struct or struct members) it is documenting.


I think this change is large and important enough to warrant a new minor  
version bump later to 6.4.0.  I'll also use that possibility to toss a lot  
of compatibility cruft for early-1990s systems overboard and require POSIX  
2001 and full C89 conformance (and reserve the right to require C99).

-- 
Matthias Andree