Code layout and debugging time

[Gary W. Swearingen]

Terry Lambert <tlambert2 at mindspring.com> writes:

> Personally, I think Linux and FreeBSD driver code *should* document
> the hardware, [...]

And it should be kept in the source code (or an Article), not in the
USER MANUAL, as seems to be SOP (eg, for the RealTek "rl" driver).
Unfortunately, it's clear from intro(4) that FreeBSD prefers to have
users slogging through the same manpages as driver developers.  But
I suppose it's practically unavoidable without paid documenters.

And, though you apparently disagree with me, the documentation shouldn't
publicly humiliate the hardware manufacturer, as the "rl" manpage does.
A private message to the manufacturer would be more seemly.  If I were
RealTek, I'd withhold ALL documentation and communication with FreeBSD
people until they stopped their anti-advertising campain against my
company.  I filed PR 31271 on this matter and it got multiple agreement
from doc-ers and got "fixed", but it seems that somebody's vicious
streak ran too deep and the nastiness was mostly restored -- and it's
much worse in the driver source.  And if RealTek has improved, as you
say, those comments certainly ought to be improved too.