On Tue, 1 Aug 2023 15:08:56 -0400 Stevie Alvarez <stevie.6strings@xxxxxxxxx> wrote: > > Also, for header files, functions do not need kernel doc comments. They > > should exist in the C files where the function is described. > > As I've been updating the documentation, I keep thinking about this. Is > there a particular reason why the documentation should reside within the > C file rather than the header? > When I think about using libraries, my immediate thought is to look at the > interface/header file to see what functions are avaiable and what they do, > not the source. I'd think that the code would jumble up my view and make > it more cumbersome and distracting to read. > All that said, I'm not sure sure if that's not the standard way of doing > things here. The reason is that users should be using the man pages that we create. But the comment around the code is to remind us (the code developers) what the code is for while we are developing. When I work on a function, I like to read the comment for that function to make sure I'm not breaking anything. In other words, users of the code should not need to be looking at the header files (I seldom do, unless there's missing man pages). If we put the comment by the prototype, then really nobody will be seeing it. We will have man pages before this is fully released. -- Steve
|