ExampleClass¶
- class docs_example.style_guide.ExampleClass(arg1: int, arg2: Optional[str] = None, arg3: str = 'item1', arg4: Optional[dict] = None)[源代码]¶
The summary line for a class docstring should fit on one line.
Describe the function of the class in a few sentences, including but not limited to what the class is and what it can do.
In the docstring, we can list some items with the following format:
item1
item2
item3
item4
If we want to quote a URL, then we can quote it like OpenMMLab. Note that there needs to be a space between the title and the link, otherwise it will not render successfully. We can also quota a link like OpenMMLab.
注解
If the class has something important to remind the user, we can show it in the note block.
警告
If the class has something important to warn the user, such as a change in the interface, we can show it in the warning block.
Sometimes we want to use formulas to represent some definitions, we can write them within lines like \(e^{i \pi}+1=0\). Or we can write it between lines like.
\[e^{i \pi}+1=0\]注解
Of course, we can also write the formula in block like \(e^{i \pi}+1=0\) or the following format.
\[e^{i \pi}+1=0\]To make it easier for users to get started quickly, we can give some introductory examples in the example block.
实际案例
>>> # initialization >>> obj = ClassDocstring(1) >>> # give a few more examples >>> obj = ClassDocstring(1, 'second parameter')
- 参数
arg1 (int) --
arg1
is the first parameter. If we want to quote a link to explain the argument, we can say that see more details at website.arg2 (str, optional) --
arg2
is the second parameter. Defaults to None. Note that if the default value is None, then you need to add optional to the parameter type. If the description of a parameter is too long, just indent it with a new line.arg3 (str) --
Of course, We can list some optional values with the following format. Defaults to
item1
.item1
item2. If the description of a parameter is too long, just indent it with a new line. Be careful to the indentation alignment between lines otherwise there will be unexpected rendering result.
arg4 (dict, optional) --
If the parameter is a dictionary, we can describe it with the following format. Defaults to None.
key1: This is a shot description of the item.
key1: This is a shot description of the item.
注解
Properties created with the
@property
decorator should be documented in the property's getter method.注解
Note that the usage of
double backticks
, single backticks, and "double quotation marks" are different. In reStructured syntax,double backticks
means a piece of code. single backticks means italics. "double quotation marks" has no special meaning, but can be used to represent a string. The usage of single backticks is different from that in Markdown, so you should pay attention to it.If the class has public attributes, they may be documented here in an
Attributes
section and follow the same formatting as a function'sArgs
section. Alternatively, attributes may be documented inline with the attribute's declaration (see __init__ method below). Note that theAttributes
section is optional.- arg3¶
Doc comment inline with attribute
- argument_list_changed(arg1: int, arg2: str = '') → None[源代码]¶
If the argument list of a method have changed, we need to reflect that in the docstring.
注解
More specifically, if the parameter is newly added, we can use the New in version 1.1.1. which 1.1.1 is the version parameter was added. If the meaning of the parameter are changed, we can use the Changed in version 1.1.1..
警告
If the parameter was renamed, we need to tell user the interface was changed in the warning block.
- property owner¶
Properties with both a getter and setter should only be documented in their getter method. If the setter method contains notable behavior, it should be mentioned here.
- Type
- return_dict(arg1: int, arg2: Union[str, list], arg3: dict) → dict[源代码]¶
Summarize the function of the method in one sentence.
Describe the function of the class in a few sentences. Of course, it is not required.
- 参数
arg1 (int) --
arg1
is the first parameter.arg2 (str | list) --
arg2
is the second parameter. This parameter may be of type string or list.arg3 (dict) --
We can describe the parameter with the following format.
key1: This is a shot description of the item.
key1: This is a shot description of the item.
- 返回
Return the output where the keys denote A meaning and values denote B. Be careful to the indentation alignment between lines otherwise there will be unexpected rendering result.
- 返回类型
- return_string(arg1: int, arg2: Union[str, list], arg3: dict) → str[源代码]¶
Summarize the function of the method in one sentence.
Describe the function of the class in a few sentences. Of course, it is not required.
注解
Do not include the self parameter in the
Args
section.- 参数
arg1 (int) --
arg1
is the first parameter.arg2 (str | list) --
arg2
is the second parameter. This parameter may be of type string or list.arg3 (dict) --
We can describe the parameter with the following format.
key1: This is a shot description of the item.
key1: This is a shot description of the item.
- 返回
Return the output.
- 返回类型