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

It seems to me that in very many cases, we don’t actually need multiple types in the docs. For the examples here, something like this could work:

some_func(p, timeout=None)

  • p: number – A parameter that takes an int or a float argument. A Decimal will work too, we’re not picky.
  • timeout: number ­– A timeout in seconds for blocking operations like connect(). If omitted (or None), use the global default timeout settings.

IOW, the “or None” spelling of “optional” is best left to automated tools.

2 Likes

I agree with Petr and earlier comment by Alex that we focus on what works best for the reader. In general, I believe spelling out of “or” or “optional” would cause the least user confusion.

1 Like

I’ve come around to using English phrasing for docs.

  • I like using “int, optional” (or a longer form as Petr shows) instead of either “int or None” or “int | None”. This is especially true where the argument isn’t meant to be an explicit None, but None is for omitted arguments.
  • I like having terms like “file-like” available for describing the type of arguments. Of course those should be linked to a description somewhere if it’s available.
  • I hope “number” would be a linkable term that mentioned the specifics, though I fear different functions might have a different idea of what a number could mean. If there isn’t a crisp unambiguous definition to link to, then we should use a written description like Petr shows.
4 Likes