Some updates to HACKING

[Russ Allbery]

Jeffrey M Vinocur <jeff at litech.org> writes:

> Is there a good reference for perldoc anywhere, particularly as would be
> useful for general documentation (i.e., non-Perl) purposes?  I've just
> been using the existing doc/pod/ stuff as a reference, but it would be
> nice to have a real reference.

> (And if not, we should document the subset of POD that we use for INN.)

The pod2man man page attempts to provide some sort of description of what
to do when writing man pages in POD, but it's not very complete.  I'll try
to whip up some sort of guide to the conventions that I've been using.
That's a good idea.

> Fine by me.

> Well, in almost all cases there's a typedef but then we go ahead and
> dereference the underlying struct directly, which completely kills any
> possibility of changing the ADT to anything except a struct later
> anyway.

> In rare cases, when there's really an abstract interface with operations
> specified, then sure, typedef.  Otherwise it's just, well, hypocritical.

In most cases, we aren't going to be able to change the data type to
something other than a struct anyway, or there would never be any reason
to do so.  C has a paucity of complex data types; usually, if something
started life as a struct, it's pretty unlikely it's ever going to become
an array or a union or something.

I'll stick something in there about cases where we actually gain something
from hiding the fact that it's a struct.

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>