I found it quite difficult to understand what this does. Would it make sense to change the description to something like this?

Transform a matrix from local to pose space (or back), taking into account options for inheritance and scale.

And then initialize matrix_local, parent_matrix and parent_matrix_local to the matrices from the bone and its parent, if not provided? The descriptions of these parameters can then explain what they override.

It seems like this was implemented starting from a more obscure/advanced use case, which is fine to support, but maybe the simpler case can be simpler to use and understand.

In D4053#91951, @Brecht Van Lommel (brecht) wrote:

And then initialize matrix_local, parent_matrix and parent_matrix_local to the matrices from the bone and its parent, if not provided? The descriptions of these parameters can then explain what they override.

The reasons it doesn't do that:

1. Ideally this method would be static (i.e. pure math) - the only reason it isn't is that in the python api all the flags are split into separate properties and you can't easily pass them all as a unit like in C.
2. Flags are stored in Bone, so this is a Bone method, and thus it doesn't have access to the pose matrices in the first place. It could use the matrix_local ones, but:
3. AFAIK RNA doesn't have a way to know if a matrix parameter is actually omitted, so for the parent ones it actually has to compare them with 0 (rely on specific default value). I.e. optional matrix parameters are best to be avoided.

It seems like this was implemented starting from a more obscure/advanced use case, which is fine to support, but maybe the simpler case can be simpler to use and understand.

4. The simple case is handled by Object.convert_space, and thus this new method is only ever needed for the complex case.

Hm, I wonder if the function should be called convert_space_local to match the naming of the Object one.