Michael Haggerty <mhag...@alum.mit.edu> 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
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to