This question is about how I should document functions in my code that require me to expose to the user some details of the implementation. (This is about public facing documentation not code comments)
I have some functions in my code, say “compute_XYZ”. And then for each such function I have a wrapper function “compute_and_save_XYZ” which runs “compute_XYZ” and writes the output to a file instead of returning it.
In the documentation for “compute_and_save_XYX” should I just say “this function is just a wrapper for compute_XYZ so see the documentation for that function to understand the meaning of these flags and parameters”, or should I repeat what each parameter of the function does?
I don’t like the idea of explaining in the documentation what functions are called by the parent, because to me this conflicts with the idea of the abstraction barrier.
In an ideal world I would just leave file IO to the end user but the program is aimed to include a nontechnical audience who does not know how to write file IO and just wants to call a single master function from a jupyter notebook that does everything for them.
I also thought about putting a simple example file IO script in the documentation itself to show how to write the output to a file, and omitting the “compute_and_save” function from the API, but my boss thinks this is too intimidating for the intended userbase