Messages in this thread | | | Date | Thu, 8 Mar 2001 14:13:55 -0600 (CST) | From | Oliver Xymoron <> | Subject | Re: [PATCH] documentation for mm.h |
| |
On Wed, 7 Mar 2001, Rik van Riel wrote:
> I've taken today to write some documentation for > include/linux/mm.h, as used in 2.4.x
Mostly good.
> + pgprot_t vm_page_prot; /* Access permissions of this VMA. */
But a lot of the comments are trivial = deadweight. Comments are best used for the bits that are magical without them, which should be few.
> + struct page *next_hash; /* Next page sharing our hash bucket in > + the pagecache hash table. */
Multiline comments at the end of the line are hard to maintain and highly susceptible to tab damage.
> + atomic_t count; /* Usage count, see below. */ > + unsigned long flags; /* atomic flags, some possibly > + updated asynchronously */
I'm sure there's a good reason why the flags aren't atomic_t but this comment would make me suspect a bug. Comments that don't agree with code are worse than no comments.
-- "Love the dolphins," she advised him. "Write by W.A.S.T.E.."
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
| |