cvs commit: src/sys/kern init_main.c kern_malloc.c md5c.c subr_autoconf.c subr_mbuf.c subr_prf.c tty_subr.c vfs_cluster.c vfs_subr.c

[Diomidis Spinellis]

Poul-Henning Kamp wrote:
> The thing which grinds in my ear about most of the tools I have ever
> heard about is "specially annotated source code" or "model reflecting
> the structure of the program" and similar.
> 
> I personally don't want to have to express the same ting multiple
> times, once for the compiler and once for each interested tool is
> N-1 times too many.

There are often hidden opportunities to avoid this problem.  As an
example, our section 2 manual pages document the error codes of each
system call using the .Er macro.  I find this type of documentation
extremely valuable; when I get a strange error from a system call I can
grep for the errno value in /sys to see what is going on.  The lists are
not complete; I have in the last year corrected two manual pages where a
given return code was missing.  I could write a tool to follow the call
graph, locate all "errno = " assignments for each function call, and
compare them against the corresponding manual page.  As I see it, the
main obstacle is the various vtables that make the static establishment
of the call graph a lot more difficult.

Note that FreeBSD is uniquely positioned to capitalize on this
opportinity: consider that the Win32 SDK does not even document the
possible errors a system call can generate and we are using a special
macro for tagging the errno values in our documentation.

Diomidis - http://www.spinellis.gr