Signed-off-by: Glenn Jocher <glenn.jocher@ultralytics.com>
Co-authored-by: Muhammad Rizwan Munawar <chr043416@gmail.com>
This commit is contained in:
Glenn Jocher 2024-01-24 19:28:02 +01:00 committed by GitHub
parent 3c1170769a
commit a2222b4283
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 80 additions and 32 deletions

View file

@ -53,27 +53,62 @@ I have read the CLA Document and I sign the CLA
When adding new functions or classes, please include a [Google-style docstring](https://google.github.io/styleguide/pyguide.html) to provide clear and concise documentation for other developers. This will help ensure that your contributions are easy to understand and maintain.
Example Google-style docstring:
!!! Example "Example Docstrings"
```python
def example_function(arg1: int, arg2: int) -> bool:
"""
Example function that demonstrates Google-style docstrings.
=== "Google-style"
Args:
arg1 (int): The first argument.
arg2 (int): The second argument.
This example shows both Google-style docstrings. Note that both input and output `types` must always be enclosed by parentheses, i.e. `(bool)`.
```python
def example_function(arg1, arg2=4):
"""
Example function that demonstrates Google-style docstrings.
Args:
arg1 (int): The first argument.
arg2 (int): The second argument. Default value is 4.
Returns:
(bool): True if successful, False otherwise.
Examples:
>>> result = example_function(1, 2) # returns False
"""
if arg1 == arg2:
return True
return False
```
Returns:
(bool): True if successful, False otherwise.
=== "Google-style with type hints"
Examples:
>>> result = example_function(1, 2) # returns False
"""
if arg1 == arg2:
return True
return False
```
This example shows both Google-style docstrings and argument and return type hints, though both are not required, one can be used without the other.
```python
def example_function(arg1: int, arg2: int = 4) -> bool:
"""
Example function that demonstrates Google-style docstrings.
Args:
arg1: The first argument.
arg2: The second argument. Default value is 4.
Returns:
True if successful, False otherwise.
Examples:
>>> result = example_function(1, 2) # returns False
"""
if arg1 == arg2:
return True
return False
```
=== "Single-line"
Smaller or simpler functions can utilize a single-line docstring. Note the docstring must use 3 double-quotes, and be a complete sentence starting with a capital letter and ending with a period.
```python
def example_small_function(arg1: int, arg2: int = 4) -> bool:
"""Example function that demonstrates a single-line docstring."""
return arg1 == arg2
```
### GitHub Actions CI Tests