Thank you for the input. I am happy at the high quality of comments to
my mail.
Seems like one really needs to have a point to make in drawing a
graph. Perhaps graphs from the source are not often useful.
> Take function ipfw_device_event in ipv4/ip_fw.c (2.1.44). The only
> reference to that is in structure ipfw_dev_notifier in the same source.
A good way to tell this to the one reading the source is to make the
ipfw_device_event static, which it now is not.
...
> To a human, all the above means that ipfw_device_event is called when
> any network device comes up, goes down, changes address, changes MTU or
> changes some interface flags.
I was hoping that a tool could dig up the values used to indicate the
purpose of calls used (NETDEV_CHANGE, NETDEV_CHANGEMTU,
NETDEV_CHANGEADDR, NETDEV_CHANGEADDR, NETDEV_DOWN, NETDEV_UP). Totally
automated tool to dig out the fact that the function can receive only
these values is difficult, as you say, because it is difficult to
couple calls to register_netdevice_notifier and notifier_call_chain
automatically.
However, they can be resolved by Linux source specific helping rules
like "parameter 2 of call to function notifier_call_chain with first
parameter &netdev_chain go to parameter 2 of member notifier_call in
structures passed to register_netdevice_notifier". Distributing the
values to all those functions that are assigned to the specified
member would be part of the standard set of rules. So this is just a
matter of querying the information extracted from the source to
generate documentation that stays up to date with reasonable effort of
updating the helping rules. I hope there are not too many of these
quite impossibly difficult indirections.
> I suspect the real answer is the equivalent of short man pages for each
> high level function. Something like :-
...
No and yes. Yes in the sense that pages for functions should be
available. I dislike this for the reason that free form documentation
easily omits important aspects of the function simply because the
writer forgot that such feature should be documented too and expresses
same feature in different ways. I'd rather have a tool to add a
description of an aspect to the description of functions if a rule
applies to the function. For example, add comment "Network device
notification function" to those functions that are values of
notifier_call member of structures passed to
register_netdevice_notifier.
This way the documentation will have this information for all such
functions even in the future by adding this one rule once. Also, it
forces to keep a list of features that are worth documenting for a
function and a standard way of expressing the feature so that it is
easier to use the documentation.
Automated tool like this can make errors (like when the structure
member receives the value through a variable), but still the errors
could be fixed (and the example error could be detected automatically)
by explicit rules and I suspect there would be fewer errors than if
documented by hand.
As to the shortness of the page, a tool with which to select the
features you want to see, would be nice, but let's think about it
after we get the data extracted and queries working.
----- Marko Kohtala - Marko.Kohtala@ntc.nokia.com, Marko.Kohtala@hut.fi