Any pointers that are guaranteed not to be NULL?

[HadrienG2]

This is another docs issue that is somewhat of a sibling to #578.

While going through the hwloc API for the purpose of writing Rust bindings, there were quite a few cases where I was wondering whether certain pointers truly were nullable, or could be safely assumed to never be NULL. I took the safe route of assuming nullability in all but the most clear-cut cases, however as a result the Rust binding API is quite Option<&T>-heavy, which makes it a bit awkward to use.

It would be nice if the documentations of pointer data structure fields, functions that return pointers, and functions that have pointer out-parameters, could state whether NULL is a valid value/output and, where not absolutely obvious, what getting a NULL output actually means (valid absence of output ? error case ?). I see that #579 started adressing this for functions, so it is possible that both this issue and #578 will be solved together.

From memory, the situation of functions that take pointers as input is a lot better, and I don't think I ever ended up wondering whether an hwloc entry point would or would not accept NULL as input.

If you need a list of modules/entry points that need such documentation care, feel free to ask!

[bgoglin]

I'll push some changes as part of #578, then we'll discuss this further.

[bgoglin]

NULL as a return value should be documented now. For others, there's still a lot to do, for instance use  \param and \param[in/out] to describe parameters precisely.