[libclang/python] Add some logical typing changes. (#138074)
This adds a few logical changes that might require discussion to the
libclang/python typing project, as the next step towards #76664 .
Some documentation is also updated to reflect the recent changes in
returned types.