cvs commit: src/share/man/man9 Makefile vm_map_entry_resize_free.9

[David Schultz]

On Mon, Sep 27, 2004, Mark W. Krentel wrote:
> > This is documentation for a simple static function, so doesn't it
> > belong in vm_map.c as a comment, where it is less likely to rot?
> 
> The true purpose of the man page is to describe the rules for
> maintaining consistency of the free space variables (adj_free and
> max_free).  I wanted to elaborate on the free space algorithm in a
> format that was too long for program comments, so I chose a manual
> page.
> 
> But that brings up the question of the right name for the man page.
> Theoretically, vm_map(9) would make sense because adj_free is a field
> in struct vm_map_entry.  But combining the two pages would clearly
> have the tail wagging the dog.
> 
> Another possibility is to pick an original name, say vm_map_freespace(9).  
> But Alan was concerned about choosing a name that looked like a
> function or struct but wasn't one.  Finally, we compromised on
> vm_map_entry_resize_free(9) since any discussion on the free space
> algorithm has to mention this function anyway.
> 
> Anyway, I think it's really too long for program comments, but feel
> free to suggest a better man page name.

We don't generally have manpages for static kernel functions, much
less for their implementation details.  (In fact, this may be the
first.)  It's great that you put together a description at this
level of detail, but my concern is that description will be wrong
when someone forgets to update the detached documentation later on.  

Personally, I have no objection to long comments.  In addition to
paragraph-long descriptions of individual functions, it's common
to have long descriptions at the top of files describing the
overall design.  (At a former employer of mine, these are called
``Big Theory Statements.'')  Moreover, your description isn't
*that* long; if it were part of vm_map.c, you wouldn't bother
repeating the structure of vm_map_entry's or their balanced tree
organization, for instance.

That's my take on it, but I'm not adamant about it, and I'm not
going to argue.  If I had that kind of time, I'd spend it doing
something more productive.  ;-)