I would prefer the function to return "bool".  But what I prefer is irrelevant, what counts is accuracy and clarity.  And to this end, the return type and the comment have to match.

For a int return value, the document should mention a condition relative to an integer value (e.g.: ==0, !=0, ==-1, <0, ==42, etc).

In this particular case, to minimize the changes, success should be defined as !=0 and failure ==0.

Although there is a bigger problem that I mentioned in that the Python C API uses two different return value standards: in most places, ==0 is success, in this case (and some other places) ==0 is a failure.

As for "implementation constraints" I don't see how making the documentation accurate affects that in any way.  If ever the implementation is expanded, the documentation will need to change.  The only alternative is to make the doc vague or simply wrong.