[RANT] Totally inadequate commenting in flat.h

[Paul Mackerras]

Looking over the recent changes in Linus' tree, I saw there was this
new file, include/linux/flat.h.  Hmmm, uninformative name, what's this
file about?  I look in the file and here is how it starts:

/* Copyright (C) 1998  Kenneth Albanowski <[e-mail]>
 *                     The Silver Hammer Group, Ltd.
 * Copyright (C) 2002  David McCullough <[e-mail]>
 */

#ifndef _LINUX_FLAT_H
#define _LINUX_FLAT_H

#define	FLAT_VERSION			0x00000004L

/*
 * To make everything easier to port and manage cross platform
 * development,  all fields are in network byte order.
 */

struct flat_hdr {
	char magic[4];
	unsigned long rev;          /* version (as above) */

etc.

*Completely* uninformative.  How is anyone supposed to know what this
relates to?  Is it something to do with a network device, or a
filesystem, or an executable format, or what?

[And no, don't reply to this telling me what it's about, add some
comments to the file instead.]

Paul.