Michael Haggerty <mhagger@xxxxxxxxxxxx> writes: > Another idea: in string-list.h, one could name parameters "sorted_list" > when they must be sorted as a precondition of the function. That sounds like a very sensible thing to do. > But before getting too hung up on finery, the effort might be better > invested adding documentation for functions that are totally lacking it, > like > > string_list_clear_func() > for_each_string_list() > for_each_string_list_item() > string_list_find_insert_index() > string_list_insert_at_index() > > While we're on the subject, it seems to me that documenting APIs like > these in separate files under Documentation/technical rather than in the > header files themselves > > - makes the documentation for a particular function harder to find, > > - makes it easier for the documentation to get out of sync with the > actual collection of functions (e.g., the 5 undocumented functions > listed above). > > - makes it awkward for the documentation to refer to particular function > parameters by name. > > While it is nice to have a high-level prose description of an API, I am > often frustrated by the lack of "docstrings" in the header file where a > function is declared. The high-level description of an API could be put > at the top of the header file. > > Also, better documentation in header files could enable the automatic > generation of API docs (e.g., via doxygen). Yeah, perhaps you may want to look into doing an automated generation of Documentation/technical/api-*.txt files out of the headers. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html