GeezerVison

You can use .. availability:: Windows (but put the directive after the class doc)

I followed the pattern in ctypes.rst because it frequently used sentences like Windows only: ....

Since this markup wasn't mentioned in the documentation guide, I overlooked it.
Is this a more modern approach?

It's widely used in the https://docs.python.org/3/library/socket.html module actually. But if it's not the pattern of ctypes maybe it's better to be consistent. We can make a follow-up PR to transform them into directives.

I removed the Availability directive and reverted to the original "Windows only: ...".

Once this PR is merged, I would like to work for replacing "Foo only: ..." with the .. availability:: Foo directive.

Referring to the socket.ioctl documentation, it seems that using :platform: Windows might be more appropriate than .. availability:: Windows. What do you think?

Alternatively, could it be that :platform: is intended to be used exclusively in module sections, as described in the documentation guide's "Module-specific markup"?

.. availability:: is generally the correct one to use. FWIW, we have some tooling to ensure it's in a correct format.
It's OK to not use it in this PR, to be consistent with the rest of the documentation. But, if you're looking for more to do in the ctypes docs, adding availability would make a great follow-up PR :)

Should it be placed here or somewhere else? because it cuts the flow of the reading where paramflags is documented afterwards. Maybe we can put it before the functions?

I was also unsure whether this was the right place to put it.

On the other hand, placing it above prototype or above FOOFUNCTYPE might seem abrupt.

Might it be appropriate to create the Exceptions section, including ArgumentError?
However, in this scope, I think making such a change that involves the "Foreign functions" section is excessive.

Well.. honestly I think it makes sense to put it in an exception section. I think it could be fine for this small docs change (I mean, it's for our own convenience). We can ask @hugovk as a docs expert.

Yes, we often have an exceptions section further down, see for example:

https://docs.python.org/3/library/json.html#exceptions

If the community agrees, creating an "Exceptions" section is no problem at all.

For now, I think I'll try placing it at the end of the document, after the "Arrays and pointers" section.

That's not very helpful. Could you document what the items are?

Based on the C implementation source code, these items are retrieved via methods of IErrorInfo¹: GetDescription, GetSource, GetHelpFile, GetHelpContext, and the ProgID obtained via using ProgIDFromCLSID and GetGUID.

However, this exception can be raised not only from foreign functions but also intentionally by passing variable-length tuples, as seen in test_win32.py and the comtypes package.

I will revise this part, taking these facts into account.

Since _ctypes is internal API that is subject to change, I think it would be best to change test_win32 and comtypes so that they raise the same 5-tuple as ctypes itself, and document that 5-tuple.

I wrote details of details.

I plan to improve test_win32 after improving this documentation.

For comtypes, I will investigate how much COMError.details is being used and then discuss the matter with the project's community to decide how to proceed.

As mentioned earlier, I would like to focus on improving the documentation in this PR.

WindowsError is now an alias of OSError.

Good catch.

Thank you.

Let's not expose private API in the docs.

You’re right, this information isn’t particularly useful in the documentation.

I’ll move it to the NEWS file as a supplement.

I think (but I'm not 100% sure) that .COMError means Sphinx will search all namespaces, not just ctypes, for a COMError. So it would be better to use ctypes.COMError explicitly: