Documenting "leaky abstractions" in an API

Python Help
1

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

2

I think you should identify the wrappers as wrappers and refer to the wrapped instead repeating doc.

3

IMO, this depends on how distinct the two API’s are intended to be.

If they’re two different API’s, then redocument to be complete, and to assert that these are two different things - with a “duplicated here for your convenience.”

If they’re part of the same API, then merely refer.

Depending on how you are formatting your documentation, assuming the redocumenting, you could use some form of preprocessor like m4 or perhaps Jinja2, so you don’t have to maintain the documentation for the same thing in two different places.