Why should we document something, just to tell people not to use it?

This field is exposed to the user who may use local PyTypeObject instances that are statically initialized (the LinuxCNC project implements that use case several places). If you do not initialize this field, then you get a warning missing initializer for member '_typeobject::tp_versions_used'.

Therefore, it should be documented (and it needs to be set to zero when statically initialized).

Sorry for the delay on the response. Please don't use a static PyTypeObject if you're running into this problem -- use a heap type (PyType_Spec) instead, which uses an array of slots rather than a struct.

Please don't use a static PyTypeObject if you're running into this problem [snip]

That is easily said, but you are too late. The static use case of PyTypeObject is already a fact and has been for a long time (like the past 19 years for LinuxCNC). I'm sure other projects also use it in a static fashion.

If you want to hide static use of PyTypeObject from the users, then you will have to go through a proper deprecation cycle. If you are not prepared to do that or there is no support for deprecation, then you should simply document every field in this structure.

BTW, the phrase "documenting the field" does not mean that you have to tell its inner secrets to all users.

The only "documenting" you must do is to acknowledge the field's existence, just like all other fields of the PyTypeObject, so all fields are listed together in the documentation. You may even tell the user that it is "for internal use only" and then be done with it. That is all.

If you want to hide static use of PyTypeObject from the users, then you will have to go through a proper deprecation cycle. If you are not prepared to do that or there is no support for deprecation, then you should simply document every field in this structure.

I think this is probably the better approach, but instead of a deprecation with a planned removal, we should just soft deprecate static types.

These days, I'd argue that static types should only stick around in public APIs for compatibility's sake. But for a maintained project like LinuxCNC, it's really not much of a chore to switch over to heap types, especially since it will help in the long run.

You may even tell the user that it is "for internal use only" and then be done with it. That is all.

The problem is that we don't really do this anywhere else, as far as I know (and if we do, we shouldn't!). It doesn't make much sense to me to document something as "this is only documented so C++ users know to set this to zero so they can avoid a warning". (It also makes it much, much more difficult to remove tp_versions_used if it's documented.)