[DOC]: C API doc strings don't always make sense with python bindings

[ngimel]

Is this a duplicate?

• I confirmed there appear to be no duplicate issues for this bug and that I agree to the Code of Conduct

Is this for new documentation, or an update to existing docs?

Update

Describe the incorrect/future/missing documentation

cuda-bindings turns some c api arguments into returns, and yet it still reuses C API doc strings that don't make sense. See e.g. on enclosed screenshot, `from and to may both be NULL`, but user doesn't control `from` and `to` so user cannot set them to NULL. There's also broken formatting where things that should not be italicized are italicized. The doc should be something like "if numEdges is 0, `to` and `from` are returned as empty lists, and the function only returns the number of edges in `numEdges`. Otherwise, `to` and `from` will have `numEdges` entries" NULL also doesn't make sense in python context.

If this is a correction, please provide a link to the incorrect documentation. If this is a new documentation request, please link to where you have looked.

No response

[leofang]

Hello Natalia! Thanks for letting us know about the discrepancy. As you may have guessed, the cuda.bindings API reference is fully automatically generated from the same C API reference, i.e., the Doxygen docstrings in the CUDA headers are the source of truth. Such automation is hard to reach 100% satisfaction when it comes to coping with the semantic differences between C and Python. Unlike other bug reports I am hesitant to commit to a local fix for binding docs on a case-by-case basis, because it adds maintenance overhead. This is one of the places where I wish a future LLM could solve systematically. It needs to be able to ingest in full the driver/runtime API references and CUDA Programming Guide, and deterministically rewrites the API reference entirely targeting Python users. That said, please do keep filing any issues you encounter! 🙂