Messages in this thread | | | Subject | Re: Take a deep breath... | From | Kohtala Marko <> | Date | 15 Jul 1997 19:44:43 +0300 |
| |
"Steven N. Hirsch" <shirsch@ibm.net> writes: > On Mon, 14 Jul 1997, David S. Miller wrote: > > I almost guarantee that 10% more effort put into documentation and > commenting would reap great rewards in terms of contributed input from the > community at large. Then, you CAN go off and design and implement the > "latest and greatest" - AFTER having paved the way for others to maintain > and fine-tune the previous "latest and greatest".
I agree mostly. The design is often based on a limited set of fundamental rules to follow and these should be more readily and explicitly available.
However, I find that the greatest problem both in documentation and designing something for the kernel is that the kernel keeps changing quite a lot. I do not disapprove of the changes, they are needed, but it still is a problem to deal with.
Some tools like ctags/etags and id-utils help a lot, but still leave a lot to be desired. They help reading and following the source code by helping in generating indices over the whole code.
I have been playing with an idea of adding some LClint directives into linux source and perhaps extending LClint to provide some additional information about the source code (call graphs, uses of structures, uses of structure members, ranges of values used). The extracted information could be used to generate documentation, for example for structures the places of usage, those corners of call graphs using the structure, summaries of what functions are called by those functions a member of structure is known to point at. Of functions the context it is run in (from which known functions the call originates), possibly what locks/semaphores are held on the call.
I am not writing about some intelligent code to design converter, but a tool to collect that data which is easy to find in source, query the data and format it to annotated graphs and text. For example, ranges of parameter and structure member values can be collected easily by taking all the places where constant values are used/assigned. Any uses of variable just adds a note of some unknown values being used. This would help in many places (with function pointers especially) and even if imperfect, not worse than nothing.
Some tools for this already exist, but I have not found a set of tools that I find worth using. LClint could be developed into data extraction and better design verification tool. Data query and formatting tools are available, but I have not found any work on a good schema for the data.
People interested in writing books can then insert these graphs and texts into their books in middle of other explanations of the kernel design. Most likely a book like this should be maintained to contain the most important design ideas and the data confirming the design.
As a bonus, LClint would check the source not to violate some design decisions. I am sure the developers of LClint would be glad to have our feedback on what is needed and even perhaps add the useful features.
-- --- Marko Kohtala - Marko.Kohtala@ntc.nokia.com, Marko.Kohtala@hut.fi
| |