How should we mark up multiple types in a type field?

Documentation
16

It looks to me that the sub-discussion about C&P from :type: fields is based on the premise that all :type: fields are marked up with typing compatible names[1]. However, this is not always the case. A lot of functions and methods take path-like and file-like objects[2]. In order to be more fair towards these, I expanded the example in the OP with this case[3]:

:param other:
   Possibly a path.
:type other: path-like object | None

vs.

:param other:
   Possibly a path.
:type other: path-like object or None

Take this into account when discussing the pros and cons of each style.

  1. int, None, etc. ↩︎

  2. other examples would be callables, and other non-basic types, often explicitly marked up using :term: or :ref: ↩︎

  3. note that path-like and file-like refs would normally be marked up using :term:, but I omitted this, since IMO it is not relevant for the discussion ↩︎

2 Likes