I keep seeing docstrings that have lines that read like this:
param : :obj: str
I can't find a reference to what :obj: stands for or does. It seems like it would denote a str object, but I also see
param : int
which doesn't seem to jibe.
Thanks.
Asked
Active
Viewed 4,201 times
13
Paka
- 185
- 2
- 8
-
1Can you copy or link some examples in context? – Patrick Haugh Dec 13 '16 at 17:38
-
See, e.g. here https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html Example: ```param2 (:obj:`int`, optional): Description of `param2`. ``` – Wolfram Arnold May 17 '20 at 00:39
2 Answers
7
This is Sphinx-related syntax to insert a link to the `str object in the standard Python documentation. See also Python Documentation (:obj:`str`) vs (str).
user1919235
- 470
- 7
- 17
3
This is not built-in Python functionality. The author of the code you're looking at is using some external tool to automatically generate documentation. It looks like Sphinx syntax, but I'm not sure.
I assume you're finding these at the docstrings for functions and methods. The are identifying the types of arguments for the automatic documentation generator to correctly document the function/method signature.
skrrgwasme
- 9,358
- 11
- 54
- 84
-
One thing to note about docstrings like this is that there is no real "standard" for formatting them. Sphinx uses an RST-based syntax and Google has a Python style guide with a different syntax. But, you can put whatever is useful to you and your users in the docstring...they're made first for humans and we only enforce standards on them to help generate pretty documentation. – Scott Colby Dec 13 '16 at 18:16