This came up in the context of SERVER-95136, but is broadly applicable.  When WT returns some error code, say EBUSY, or really anything other than 0, we should be able to tell the possible ways that this could happen.

What follows is an implementation path I had in mind for this, but there may be other simpler solutions! There are a few parts to this.  Doing a subset of this may also be useful.

Part one: run some static analysis over WT source tree to answer two questions for each function - what other functions are called by this one?  what literal return values are returned?  For the second we are looking for "return (EINVAL)", for example. or assignments like: "ret = WT_NOTFOUND", knowing that many functions return ret.  There are some tricky elements - for example, for the first question, we probably want to run the c-preprocessor first to make sure we're seeing through any macros.  And yet, the c-preprocessor will replace WT_NOTFOUND by a number. There are ways around this particular problem, but there are probably a bunch of other details to be solved here, and maybe a 98% solution is good enough.  Also, one might imagine some existing (or to-be-built) clang plugin that could help with this.  If not, I'd bet is all doable via scripts - many of the scripts in dist have equal sophistication.

Second part: Once you have answers to those questions for every function in WT, some recursive logic can be applied.  One way would be to digest this all and spit out for each function:

__wt_some_function()
    can return EINVAL, EBUSY, WT_NOTFOUND, (os_read_returns)

    EINVAL can be returned from 
      __wt_some_function at foo.c:123 calling
      __wt_other_function at bar.c:456 calling
      __wt_last_functions at last.c:789 returns EINVAL

(os_read_returns) might be shorthand for anything the OS's read returns.  Store it in build/return_values_reference.txt!

As you might guess, this output may be huge - there may be hundreds of different ways that EINVAL can be returned.  So, maybe we store the simple dependencies in a concise way (for any function, what are the functions it calls - at what line number, and what explicit returns does it have at what line number).  Once you have this, then you could build a tool to query that info - and ask for all the ways that __wt_some_function can return EINVAL.

Third part: If you knew that __wt_open_session could return X,Y,Z, and you had a mapping that told you that __wt_open_session is just WT_CONNECTION::open_session, then you could update the doc directly with return value information.

I think a lot of things are possible here, it might make an interesting skunk demo and would probably be helpful in debugging a certain class of failures.

Another wild thought - are AI tools up to answering queries like this, given the source tree (maybe not??), and could an AI tool help build the scripts that does some of this, like Part one (maybe??).